perf(vite): add plugin hook filter

[TheAlexLichter]

Summary

This PR adds plugin hook filters to the Vite plugin. They are backwards-compatible, having no impact on older Vite versions as the check for isPotentialCssRootFile is still included.

It can be dropped once you don't need to support older Vite versions.

See also

e18e/ecosystem-issues#171

[coderabbitai]

Walkthrough

Per-serve and per-build async transform functions were replaced by a single transform object with a filter and a handler. The filter excludes /.vite/, SPECIAL_QUERY_RE, and COMMON_JS_PROXY_RE and includes CSS files, &lang.css, and INLINE_STYLE_ID_RE. The handler preserves prior logic: short-circuits for non-CSS-root ids, initializes instrumentation, resolves the CSS root, generates CSS, optionally deletes the root on failure, and finalizes instrumentation. The build path now mirrors the serve path. Public/plugin signatures were not changed.

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'perf(vite): add plugin hook filter' clearly and concisely describes the main change: adding plugin hook filters to the Vite plugin for performance optimization.
Description check	✅ Passed	The PR description provides relevant context about adding hook filters to the Vite plugin, mentions backwards-compatibility, and references the related issue, making it directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5395ed8 and 8c1d1f5.

📒 Files selected for processing (1)

• packages/@tailwindcss-vite/src/index.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/@tailwindcss-vite/src/index.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Linux / vite
• GitHub Check: Linux / postcss
• GitHub Check: Linux / upgrade
• GitHub Check: Linux

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4455051 and 7554091.

📒 Files selected for processing (1)

• packages/@tailwindcss-vite/src/index.ts (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: Linux / upgrade
• GitHub Check: Linux / webpack
• GitHub Check: Linux / cli
• GitHub Check: Linux / postcss
• GitHub Check: Linux / vite
• GitHub Check: Linux

🔇 Additional comments (1)

packages/@tailwindcss-vite/src/index.ts (1)

107-123: LGTM! Handler logic correctly preserves original behavior.

The handler implementations maintain the exact same functional behavior as the previous transform functions. The retention of the isPotentialCssRootFile check provides a safety net and ensures backwards compatibility if the filter is not supported by older Vite versions.

Also applies to: 140-165

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify Vite version compatibility for the filter syntax.

The new filter object syntax is a Vite-specific feature. Ensure that the minimum supported Vite version in the package dependencies supports this transform-with-filter-and-handler pattern.

Run the following script to check the Vite version requirements:

---

🏁 Script executed:

#!/bin/bash
# Check minimum Vite version specified in package.json

# Find and display Vite peer dependencies or dependencies
cat package.json | jq '.peerDependencies.vite // .dependencies.vite // .devDependencies.vite'

Length of output: 4

---

[/run_scripts]

---

🏁 Script executed:

#!/bin/bash
# Find and display the @tailwindcss-vite package.json with Vite dependency

find . -path "*/packages/@tailwindcss-vite/package.json" -type f | head -1 | xargs cat 2>/dev/null || echo "File not found"

Length of output: 1007

---

[/web_search]

---

🌐 Web query:

Vite transform filter property not supported older version error

💡 Result:

I need a bit more info to diagnose. Please provide:

• Exact error text and stack trace.
• Your Vite version (from package.json or npm list vite).
• The plugin code (or the transform hook where you set a filter property).
• A minimal repro or repository link, if possible.

Meanwhile try these quick checks:

1. If your plugin uses a "filter" property on the transform hook (e.g. transform.filter = /.../), remove it and instead use a manual ID check inside transform or use createFilter from @rollup/pluginutils:
   • const filter = createFilter(include, exclude)
   • if (!filter(id)) return
2. Upgrade Vite to a current version (npm i -D vite@latest) — older Vite/Rollup plugin API compatibility may lack newer plugin features.
3. If you’re adapting a Rollup plugin, ensure you follow Vite’s plugin API (transform hook signature: async transform(code, id) { ... }).
4. Share the failing plugin code snippet if you want a precise fix.

Provide the requested details and I’ll give an exact fix.

---

[/web_search]

---

🌐 Web query:

Vite 6.3.0 release notes transform filter changelog

💡 Result:

Summary: The Vite changelog shows that "hook filters" (transform/filter for plugin hooks) were implemented as a feature in the 6.3.0 beta series and appear in the 6.3.x changelog. The key entry is "feat: implement hook filters (#19602)" in the 6.3.0-beta.0 notes; v6.3.0 stable was released 2025-04-16. [1][2]

Sources

• Changelog excerpt showing 6.3.0 entries including the beta feature "implement hook filters" and v6.3.0 release date. [1]
• Vite Releases page / announcement (Vite 6 stable). [2]

---

Update peerDependencies to enforce Vite 6.3.0+ minimum.

The transform filter syntax used at lines 100-106 requires Vite 6.3.0 or later. The current peerDependencies allows Vite 5.x and Vite 6.0-6.2, which do not support the filter property. This will cause the transform hook to fail silently or error in incompatible versions.

Update packages/@tailwindcss-vite/package.json:

"peerDependencies": {
  "vite": "^6.3.0 || ^7"
}

🤖 Prompt for AI Agents

In packages/@tailwindcss-vite/src/index.ts around lines 100 to 106, the
transform.filter usage requires Vite 6.3.0+; open
packages/@tailwindcss-vite/package.json and update the peerDependencies entry
for vite to "vite": "^6.3.0 || ^7" (or equivalent semver expression) then run
dependency install/update to refresh lockfile/CI so the new peer requirement is
enforced.

[TheAlexLichter]

@coderabbitai The syntax is backwards-compatible as the original check is still included in the handler function.

[coderabbitai]

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

[thecrypticace]

Ah, good call! Should probably add a test for rolldown-vite to our integrations too (I'll do that later in a separate PR).

Left one comment for you

[thecrypticace]

Probably will end up doing a release next week at some point if I can get a couple of bug fixes into core.

Will be testable via our insiders build in like 20m or so:

npm install tailwindcss@insiders @tailwindcss/vite@insiders