Skip to content

Commit 00ef99d

Browse files
authored
Do not force full page reloads when using @tailwindcss/vite (#20414)
This PR removes all of the custom HMR handling we had in the `@tailwindcss/vite` plugin. When Vite 7.1 was introduced, Vite stopped performing a full page reload for unknown files and instead started performing normal `hmr` updates. This resulted in this issue: #19637 At the time, it felt like something we could easily re-add: if a file is not covered by Vite, we can perform a `full-reload`. This meant that a `.php` file would trigger a full page reload as expected. The reason the `.php` file triggered Vite in the first place is because those files were scanned by us (`@tailwindcss/vite`) so it made sense. However, this then resulted in a plethora of issues, and it feels a bit like a game of whac-a-mole. - #19744 - #19903 - #20320 - #20378 - #20411 Fixes: #19744 Fixes: #19903 Fixes: #20320 Fixes: #20378 Fixes: #20411 We kept updating the logic by safelisting certain extensions, checking different servers and/or environments, handling the fact that `server` in the callback could be absent in `experimental.bundledDev` mode, etc. etc. Now, when investigating the last issue (#20411), I can trigger full reloads by changing `.json`, `.yaml` or `.svg` files. This makes sense since they aren't handled by default. So thinking about this more, I think it's just not Tailwind's responsibility to tell Vite to reload the browser or not. Yes, we use the `addWatchFile` API, so files are being watched because of us. However, our only goal is to update the `.css` file (and HMR that). This means that we can just drop all the custom HMR handling we have in `@tailwindcss/vite`. This also means that #19637 would regress and won't trigger full page reloads. But this can be easily handled by a plugin responsible for this behavior: - https://github.com/ElMassimo/vite-plugin-full-reload ## Test plan 1. All tests pass 2. Manually tested and changing unknown files don't result in a full page reload
1 parent b9286a7 commit 00ef99d

5 files changed

Lines changed: 195 additions & 269 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2727
- Ensure root `theme('…')` namespace lookups in JavaScript plugins and config files return the full namespace object instead of the value of its `DEFAULT` key ([#20399](https://github.com/tailwindlabs/tailwindcss/pull/20399))
2828
- Skip ignored directories entirely when computing watch globs (`scanner.globs`), instead of walking their full contents on every rebuild ([#20408](https://github.com/tailwindlabs/tailwindcss/pull/20408))
2929
- Oxide: drop invalid UTF-8 candidates ([#20389](https://github.com/tailwindlabs/tailwindcss/pull/20389))
30+
- `@tailwindcss/vite` no longer forces a full page reload for external files (e.g.: `.php` files) ([#20414](https://github.com/tailwindlabs/tailwindcss/issues/20414))
3031

3132
## [4.3.3] - 2026-07-16
3233

‎integrations/vite/index.test.ts‎

Lines changed: 28 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -580,11 +580,11 @@ describe.each(['postcss', 'lightningcss'])('%s', (transformer) => {
580580
},
581581
)
582582

583-
describe.sequential.each([['^6'], ['7.0.8'], ['7.1.12'], ['7.3.1'], ['8.0.0']])(
583+
describe.each([['^6'], ['7.0.8'], ['7.1.12'], ['7.3.1'], ['8.0.0']])(
584584
'Using Vite %s',
585585
(version) => {
586586
test(
587-
'external source file changes trigger a full reload',
587+
'external source file changes update the CSS',
588588
{
589589
fs: {
590590
'package.json': json`{}`,
@@ -661,26 +661,33 @@ describe.each(['postcss', 'lightningcss'])('%s', (transformer) => {
661661
expect(styles).toContain(candidate`content-['project-b/src/index.php']`)
662662
})
663663

664-
// Flush all messages so that we can be sure the next messages are from
665-
// the file changes we're about to make
664+
// Flush all messages so that we can be sure the next messages are
665+
// from the file changes we're about to make
666666
process.flush()
667667

668-
// Changing an external .php file should trigger a full reload
668+
// Changing an external .php file hot-updates the generated CSS
669669
{
670670
await fs.write(
671671
'project-b/src/index.php',
672672
txt`<div class="content-['updated:project-b/src/index.php']"></div>`,
673673
)
674674

675-
// Ensure the page reloaded
675+
// On Vite < 7.1, Vite itself hard-invalidates watched files that
676+
// aren't part of the module graph and reloads the page.
677+
//
678+
// On newer versions nothing reloads the page: the CSS hot-updates
679+
// through the regular pipeline because the changed file is a
680+
// watch dependency of the CSS root.
681+
//
682+
// Reloading the page for external template changes is the
683+
// responsibility of the backend integration (e.g. `laravel-vite-plugin`'s `refresh` option, or `vite-plugin-full-reload`).
684+
//
685+
// https://github.com/tailwindlabs/tailwindcss/issues/20411
676686
if (version === '^6' || version === '7.0.8') {
677687
await process.onStdout((m) => m.includes('page reload') && m.includes('index.php'))
678688
} else {
679-
await process.onStderr(
680-
(m) => m.includes('vite:hmr (client)') && m.includes('index.php'),
681-
)
689+
await process.onStdout((m) => m.includes('hmr update') && m.includes('index.css'))
682690
}
683-
await process.onStderr((m) => m.includes('vite:hmr (ssr)') && m.includes('index.php'))
684691

685692
// Ensure the styles were regenerated with the new content
686693
let styles = await fetchStyles(url, '/index.html')
@@ -853,7 +860,6 @@ describe.each(['postcss', 'lightningcss'])('%s', (transformer) => {
853860
let styles = await fetchStyles(url, '/index.html')
854861
expect(styles).toContain(candidate`content-['updated:src/lazy.tsx']`)
855862
})
856-
expect(await fs.read('project-a/hmr.log')).not.toContain('full-reload')
857863
}
858864

859865
// The same holds for a custom file type as long as some file of the
@@ -868,7 +874,6 @@ describe.each(['postcss', 'lightningcss'])('%s', (transformer) => {
868874
let styles = await fetchStyles(url, '/index.html')
869875
expect(styles).toContain(candidate`content-['updated:src/comp-b.custom']`)
870876
})
871-
expect(await fs.read('project-a/hmr.log')).not.toContain('full-reload')
872877
}
873878

874879
// Changing a scanned stylesheet that is not part of the module graph
@@ -893,23 +898,26 @@ describe.each(['postcss', 'lightningcss'])('%s', (transformer) => {
893898
let log = await fs.read('project-a/hmr.log')
894899
expect(log.split('"type":"update"').length).toBeGreaterThan(updates)
895900
})
896-
expect(await fs.read('project-a/hmr.log')).not.toContain('full-reload')
897901
}
898902

899-
// Changing an external file (e.g. a PHP template) should still trigger
900-
// a full reload. This must work even though `snippet.php` is part of
901-
// the module graph via the `?raw` import: a query import only pulls
902-
// the file's contents into the graph (and creates an untransformed
903-
// module node for the underlying file), it is not evidence that Vite
904-
// processes `.php` files as modules.
903+
// Changing an external file (e.g. a PHP template) hot-updates the
904+
// generated CSS but does not trigger a full reload either. Reloading the
905+
// page for external template changes is the responsibility of the backend
906+
// integration (e.g. `laravel-vite-plugin`'s `refresh` option, or
907+
// `vite-plugin-full-reload`).
908+
//
909+
// https://github.com/tailwindlabs/tailwindcss/issues/20411
905910
{
911+
let updates = (await fs.read('project-a/hmr.log')).split('"type":"update"').length
912+
906913
await fs.write(
907914
'project-b/src/index.php',
908915
html`<div class="content-['updated:project-b/src/index.php']"></div>`,
909916
)
910917

911918
await retryAssertion(async () => {
912-
expect(await fs.read('project-a/hmr.log')).toContain('full-reload')
919+
let log = await fs.read('project-a/hmr.log')
920+
expect(log.split('"type":"update"').length).toBeGreaterThan(updates)
913921
})
914922

915923
let styles = await fetchStyles(url, '/index.html')

‎integrations/vite/preact.test.ts‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
import { candidate, css, fetchStyles, html, json, retryAssertion, test, ts, txt } from '../utils'
2+
3+
test(
4+
'dev mode',
5+
{
6+
fs: {
7+
'package.json': json`
8+
{
9+
"type": "module",
10+
"dependencies": {
11+
"preact": "^10"
12+
},
13+
"devDependencies": {
14+
"@preact/preset-vite": "^2",
15+
"@tailwindcss/vite": "workspace:^",
16+
"tailwindcss": "workspace:^",
17+
"vite": "^8"
18+
}
19+
}
20+
`,
21+
'vite.config.ts': ts`
22+
import fs from 'node:fs'
23+
import path from 'node:path'
24+
import preact from '@preact/preset-vite'
25+
import tailwindcss from '@tailwindcss/vite'
26+
import { defineConfig } from 'vite'
27+
28+
export default defineConfig({
29+
plugins: [
30+
tailwindcss(),
31+
preact(),
32+
{
33+
// Log all HMR payloads to a file so the test can assert on them
34+
name: 'hmr-wiretap',
35+
configureServer(server) {
36+
let logFile = path.resolve('hmr.log')
37+
fs.writeFileSync(logFile, '')
38+
for (let environment of Object.values(server.environments)) {
39+
let send = environment.hot.send.bind(environment.hot)
40+
environment.hot.send = (payload) => {
41+
fs.appendFileSync(logFile, JSON.stringify(payload) + '\\n')
42+
return send(payload)
43+
}
44+
}
45+
},
46+
},
47+
],
48+
})
49+
`,
50+
'index.html': html`
51+
<html>
52+
<head>
53+
<link rel="stylesheet" href="./src/index.css" />
54+
</head>
55+
<body>
56+
<div id="app"></div>
57+
<script type="module" src="./src/main.tsx"></script>
58+
</body>
59+
</html>
60+
`,
61+
'src/main.tsx': ts`
62+
import { render } from 'preact'
63+
import { App } from './app'
64+
65+
render(<App />, document.getElementById('app')!)
66+
`,
67+
'src/app.tsx': ts`
68+
import { useState } from 'preact/hooks'
69+
70+
export function App() {
71+
const [count, setCount] = useState(0)
72+
return (
73+
<button className="underline" onClick={() => setCount((c) => c + 1)}>
74+
Count: {count}
75+
</button>
76+
)
77+
}
78+
`,
79+
'src/index.css': css`@import 'tailwindcss';`,
80+
},
81+
},
82+
async ({ fs, spawn, expect }) => {
83+
let process = await spawn('pnpm vite dev')
84+
await process.onStdout((m) => m.includes('ready in'))
85+
86+
let url = ''
87+
await process.onStdout((m) => {
88+
let match = /Local:\s*(http.*)\//.exec(m)
89+
if (match) url = match[1]
90+
return Boolean(url)
91+
})
92+
93+
await retryAssertion(async () => {
94+
let styles = await fetchStyles(url)
95+
expect(styles).toContain(candidate`underline`)
96+
})
97+
98+
// Load the component modules, like a browser visiting the page would
99+
await fetch(`${url}/src/main.tsx`)
100+
await fetch(`${url}/src/app.tsx`)
101+
102+
// Editing a component keeps HMR intact: new classes are delivered through
103+
// a regular update, not a full page reload (which would lose all state)
104+
{
105+
await fs.write(
106+
'src/app.tsx',
107+
ts`
108+
import { useState } from 'preact/hooks'
109+
110+
export function App() {
111+
const [count, setCount] = useState(0)
112+
return (
113+
<button className="underline flex" onClick={() => setCount((c) => c + 1)}>
114+
Count: {count}
115+
</button>
116+
)
117+
}
118+
`,
119+
)
120+
121+
await retryAssertion(async () => {
122+
let styles = await fetchStyles(url)
123+
expect(styles).toContain(candidate`underline`)
124+
expect(styles).toContain(candidate`flex`)
125+
})
126+
expect(await fs.read('hmr.log')).toContain('"type":"update"')
127+
expect(await fs.read('hmr.log')).not.toContain('full-reload')
128+
}
129+
130+
// Changing a scanned file that is not part of the module graph (e.g.
131+
// `package.json`, which package managers and other tooling write to while
132+
// the dev server is running) should not trigger a full reload either —
133+
// that would destroy client state. New candidates should still be picked
134+
// up because the file is a watch dependency of the CSS root, so the CSS
135+
// hot-updates through Vite's regular pipeline.
136+
//
137+
// https://github.com/tailwindlabs/tailwindcss/issues/20411
138+
{
139+
await fs.write(
140+
'package.json',
141+
txt`
142+
{
143+
"type": "module",
144+
"description": "content-['package.json']",
145+
"dependencies": {
146+
"preact": "^10"
147+
},
148+
"devDependencies": {
149+
"@preact/preset-vite": "^2",
150+
"@tailwindcss/vite": "workspace:^",
151+
"tailwindcss": "workspace:^",
152+
"vite": "^8"
153+
}
154+
}
155+
`,
156+
)
157+
158+
await retryAssertion(async () => {
159+
let styles = await fetchStyles(url)
160+
expect(styles).toContain(candidate`content-['package.json']`)
161+
})
162+
expect(await fs.read('hmr.log')).not.toContain('full-reload')
163+
}
164+
},
165+
)

‎packages/@tailwindcss-vite/src/index.test.ts‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

0 commit comments

Comments
 (0)