refactor handling of full reload logic

RobinMalfait · RobinMalfait · commit 6f749ababb41 · 2026-02-17T17:54:04.000+01:00
When you use the `@source` directive in your CSS file, then internally
we will call `addWatchFile` for each of the matching files. This way
Vite will watch these files and trigger the `@tailwindcss/vite` plugin
when things change.

However, with external files we need to make sure that we trigger a full
page reload to see any effect. For example when a .php file changed. The
default behavior in Vite would be to trigger a hot update of the
index.css file. Which is correct for updating the CSS, but since the
.php file is just an asset it won't have any effect on the current page.

The original logic assumed that "asset" modules (any module with type of
asset and/or id=undefined) are not in the module graph, but in my
testing it looks like they are part of the module graph (because we call
`addWatchFile` on these files).

This means that we need another way of knowing whether or not the module
should result in a full page reload or not.

To do this, the `handleHotUpdate` receives an array of modules which we
need to analyze. For example a .js file will have a type of `js` in one
module, but it will also have a type of `asset` in the other module.
This is because of the `addWatchFile` that we added.

Now, the `handleHotUpdate` is going to be deprecated soon, so we also
updated to the `hotUpdate` API instead.

If only some of the modules are asset modules, then we can let Vite do
its job, aka do a hot module replacement. If all of the modules are
assets, then we have to determine whether the file is part of any of the
CSS file sources.

We already have a concept of a "root" which maps to a CSS file handled
by Tailwind CSS and we now also expose the scanned files so we can
match these against the file that was updated.

These roots are indexed by environment, which is one reason why we
switched to the `hotUpdate` API because `this.environment` is available
there.

To be 100% sure, we check the current file and walk up the tree
(importers) to see if any of its files is part of a Tailwind CSS root.

Once we reach a root and if that root has a scanned file of the current
file that changed, then we know to do a full page reload.

I don't think it matters _which_ root it belonged to because we will
perform a full reload anyway. I guess in theory if we changed a file
where its contents is currently not on the page then maybe we shouldn't
reload, but we can improve that if this is causing issues later.
diff --git a/packages/@tailwindcss-vite/src/index.ts b/packages/@tailwindcss-vite/src/index.ts
@@ -9,6 +9,7 @@ import {
 } from '@tailwindcss/node'
 import { clearRequireCache } from '@tailwindcss/node/require-cache'
 import { Scanner } from '@tailwindcss/oxide'
+import { realpathSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import type { Environment, Plugin, ResolvedConfig, ViteDevServer } from 'vite'
@@ -95,29 +96,6 @@ export default function tailwindcss(opts: PluginOptions = {}): Plugin[] {
         servers.push(server)
       },
 
-      handleHotUpdate({ server, file }) {
-        // If the changed file is being watched by Tailwind but isn't part of
-        // the module graph (like a PHP or HTML file), we need to trigger a full
-        // reload manually.
-        if (
-          !server.moduleGraph.getModulesByFile(file) &&
-          Object.entries(server.watcher.getWatched()).some(([dir, files]) => {
-            return (
-              (file === dir || file.startsWith(dir + path.sep)) &&
-              files.includes(path.basename(file))
-            )
-          })
-        ) {
-          let payload = { type: 'full-reload' as const, path: '*' }
-          if (server.hot) {
-            server.hot.send(payload)
-          } else {
-            server.ws.send(payload)
-          }
-          return []
-        }
-      },
-
       async configResolved(_config) {
         config = _config
         isSSR = config.build.ssr !== false && config.build.ssr !== undefined
@@ -174,6 +152,64 @@ export default function tailwindcss(opts: PluginOptions = {}): Plugin[] {
           return result
         },
       },
+
+      hotUpdate({ file, modules, timestamp, server }) {
+        // Ensure full-reloads are triggered for files that are being watched by
+        // Tailwind but aren't part of the module graph (like PHP or HTML
+        // files). If we don't do this, then changes to those files won't
+        // trigger a reload at all since Vite doesn't know about them.
+        {
+          // It's a little bit confusing, because due to the `addWatchFile`
+          // calls, it _is_ part of the module graph but nothing is really
+          // handling those files. These modules typically haven an id of
+          // undefined and/or have a type of 'asset'.
+          //
+          // If we call `addWatchFile` on a file that is part of the actual
+          // module graph, then we will see a module for it with a type of `js`
+          // and a type of `asset`. We are only interested if _all_ of them are
+          // missing an id and/or have a type of 'asset', which is a strong
+          // signal that the changed file is not being handled by Vite or any of
+          // the plugins.
+          //
+          // Note: in Vite v7.0.6 the modules here will have a type of `js`, not
+          // 'asset'. But it will also have a `HARD_INVALIDATED` state and will
+          // do a full page reload already.
+          let isExternalFile = modules.every((mod) => mod.type === 'asset' || mod.id === undefined)
+          if (!isExternalFile) return
+
+          for (let env of [this.environment.name, 'client']) {
+            let roots = rootsByEnv.get(env)
+            if (roots.size === 0) continue
+
+            // If the file is not being watched by any of the roots, then we can
+            // skip the reload since it's not relevant to Tailwind CSS.
+            if (!isScannedFile(file, modules, roots)) {
+              continue
+            }
+
+            // https://vite.dev/changes/hotupdate-hook#migration-guide
+            let invalidatedModules = new Set<vite.EnvironmentModuleNode>()
+            for (let mod of modules) {
+              this.environment.moduleGraph.invalidateModule(
+                mod,
+                invalidatedModules,
+                timestamp,
+                true,
+              )
+            }
+
+            if (env === this.environment.name) {
+              this.environment.hot.send({ type: 'full-reload' })
+            } else if (server.hot.send) {
+              server.hot.send({ type: 'full-reload' })
+            } else if (server.ws.send) {
+              server.ws.send({ type: 'full-reload' })
+            }
+
+            return []
+          }
+        }
+      },
     },
 
     {
@@ -294,6 +330,10 @@ class Root {
     private customJsResolver: (id: string, base: string) => Promise<string | false | undefined>,
   ) {}
 
+  get scannedFiles() {
+    return this.scanner?.files ?? []
+  }
+
   // Generate the CSS for the root file. This can return false if the file is
   // not considered a Tailwind root. When this happened, the root can be GCed.
   public async generate(
@@ -475,3 +515,38 @@ class Root {
     return false
   }
 }
+
+function isScannedFile(
+  file: string,
+  modules: vite.EnvironmentModuleNode[],
+  roots: Map<string, Root>,
+) {
+  let seen = new Set()
+  let q = [...modules]
+  while (q.length > 0) {
+    let module = q.shift()!
+    if (seen.has(module)) continue
+    seen.add(module)
+
+    if (module.id) {
+      let root = roots.get(module.id)
+
+      if (root) {
+        // If the file is part of the scanned files for this root, then we know
+        // for sure that it's being watched by any of the Tailwind CSS roots. It
+        // doesn't matter which root it is since it's only used to know whether
+        // we should trigger a full reload or not.
+        if (root.scannedFiles.includes(file) || root.scannedFiles.includes(realpathSync(file))) {
+          return true
+        }
+      }
+    }
+
+    // Keep walking up the tree until we find a root.
+    for (let importer of module.importers) {
+      q.push(importer)
+    }
+  }
+
+  return false
+}
