Avoid full reload when CSS-like HMR is handled by another plugin

[benpsnyder]

Summary

Fixes the @tailwindcss/vite HMR fallback that was forcing a full page reload for CSS-like watched files even when another plugin was already handling the stylesheet update.

Cross-References

Item	Link
Framework-side investigation and repro harness	analogjs/analog#2226 (comment)
Upstream bug report	#19903

Repro Shape

Aspect	Value
Framework	Analog.js + Angular component stylesheets
Bundler	Vite 8
Tailwind package	@tailwindcss/vite
Observed behavior	one component stylesheet edit triggers full-reload, then later css-update
Expected behavior	preserve targeted CSS HMR without the earlier page reload

Root Cause

Step	Behavior
1	@tailwindcss/vite sees the changed stylesheet as an external watched file
2	its hotUpdate(...) fallback sends full-reload
3	the framework stylesheet pipeline later sends a valid css-update for the same edit
4	the full reload wins the race and the page reloads unnecessarily

Fix

The change in packages/@tailwindcss-vite/src/index.ts narrows the external-file reload fallback:

Before	After
CSS-like watched files could trigger the generic external-file full-reload path	CSS-like files are excluded from that fallback because another plugin may still own stylesheet HMR
Tailwind treated asset-only / missing-id modules as sufficient evidence that nothing else handled the file	Tailwind still keeps the fallback for true external scanned files, but avoids upgrading CSS-like files to reloads

Regression Coverage

The integration test covers the reproduced handoff pattern:

Assertion	Purpose
log contains "type":"update"	proves another plugin handled the change through HMR
log does not contain "type":"full-reload"	proves Tailwind did not force a competing page reload
fixture scoped to postcss	matches the reproduced Analog pipeline

Test Plan

pnpm exec vitest --root=./integrations integrations/vite/index.test.ts -t "css-like scanned file changes do not force a full reload when another plugin handles CSS HMR"

[coderabbitai]

Walkthrough

Adds a Vite dev/HMR test that scaffolds a workspace where a custom component-style-plugin rewrites src/component-wrapper.css to import Tailwind and inline src/probe.component.css, watches probe.component.css, and on updates calls environment.hot.send with type "update" for /src/component-wrapper.css while returning no module updates. A hmrWiretap logs server.ws.send and environment.hot.send payloads. The test runs pnpm vite dev --debug hmr, modifies probe.component.css (bg-blue-500 → bg-red-500), and asserts the log contains "type":"update" and not "type":"full-reload". Also updates the Tailwind Vite plugin hotUpdate hook to early-return (skip full-reload) when isPotentialCssRootFile(file) is true.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Avoid full reload when CSS-like HMR is handled by another plugin' directly and clearly summarizes the main change: preventing unnecessary full page reloads when another plugin manages CSS HMR.
Description check	✅ Passed	The PR description is comprehensive and directly related to the changeset. It explains the root cause, fix, test coverage, and includes relevant cross-references.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@integrations/vite/index.test.ts`:
- Around line 681-689: The test fixture uses __dirname inside the Vite config
which is ESM-incompatible; update the hmrWiretap path resolution in the
defineConfig block so it constructs an absolute path from import.meta.url
instead of __dirname (locate the hmrWiretap(...) call and replace the
__dirname-based resolver with one that resolves via import.meta.url, e.g.,
convert import.meta.url to a file path and then resolve 'hmr.log' from that
directory before passing to hmrWiretap).

In `@packages/`@tailwindcss-vite/src/index.ts:
- Around line 226-231: The early return on isPotentialCssRootFile(file) skips
Tailwind's watched-file invalidation; instead of returning immediately, ensure
you still invoke Tailwind's invalidation/rebuild for watched sources before
bailing out. Update the branch in the hot-update/watch handler (the block using
isPotentialCssRootFile) to call the plugin's watched-file invalidation method
(e.g., the function that currently handles scanned `@source` changes /
rebuilds—refer to the module's watched-file invalidation or rebuild function)
and only skip forcing a full-page reload; do not skip the internal
invalidate/rebuild step for the given file.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 318c5b69-eef8-4003-9fa8-1da5feae85a7

📥 Commits

Reviewing files that changed from the base of the PR and between e01946f and e6833b7.

📒 Files selected for processing (2)

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