Do not retain the finished build's plugin context in @tailwindcss/vite

CHANGELOG.md

@@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Sort `min-*`, `max-*`, and container query variants with decimal values numerically (e.g. `min-[40.25rem]` before `min-[40.5rem]`) ([#20512](https://github.com/tailwindlabs/tailwindcss/pull/20512))
 - Ensure CSS comments ending with `\*/` are closed correctly instead of swallowing the CSS that follows (e.g. `/* C:\temp\*/`) ([#20508](https://github.com/tailwindlabs/tailwindcss/pull/20508))
 - Improve style invalidation performance of `group-*` and `peer-*` variants ([#20513](https://github.com/tailwindlabs/tailwindcss/pull/20513))
+- `@tailwindcss/vite` no longer keeps a finished build's plugin context alive, which could retain multiple GB of memory in long-lived build processes (e.g. Astro static builds) ([#20503](https://github.com/tailwindlabs/tailwindcss/pull/20503))
 
 ## [4.3.3] - 2026-07-16
 

integrations/vite/plugin-context-leak.test.ts

@@ -0,0 +1,179 @@
+import { css, js, json, test } from '../utils'
+
+// The build plugin used to cache a `Root` (and its compiler) for the
+// lifetime of the plugin instance without ever releasing it, which kept the
+// `PluginContext` of the `transform` call that created it (and everything
+// reachable through it, e.g. a finished Rolldown bundle) alive long after
+// the build finished. Only observable with Vite 8's Rolldown bundler, not
+// with Rollup.
+//
+// https://github.com/tailwindlabs/tailwindcss/issues/20501
+test(
+  'does not keep the transform PluginContext alive after a build finishes',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "type": "module",
+          "dependencies": {
+            "@tailwindcss/vite": "workspace:^",
+            "tailwindcss": "workspace:^"
+          },
+          "devDependencies": {
+            "vite": "^8"
+          }
+        }
+      `,
+      'src/app.css': css`@import 'tailwindcss';`,
+      'src/main.js': js`import './app.css'`,
+      'probe.mjs': js`
+        import { build } from 'vite'
+        import tailwindcss from '@tailwindcss/vite'
+
+        const NAME = '@tailwindcss/vite:generate:build'
+
+        let ctxRef = null
+        let probeRan = false
+
+        function instrument(plugins) {
+          return plugins.map((plugin) => {
+            if (plugin.name !== NAME) return plugin
+            let original = plugin.transform.handler
+            return {
+              ...plugin,
+              transform: {
+                ...plugin.transform,
+                handler(...args) {
+                  ctxRef ??= new WeakRef(this)
+                  probeRan = true
+                  return original.apply(this, args)
+                },
+              },
+            }
+          })
+        }
+
+        // Keep the plugins reachable so only the plugin's own cache can be
+        // what keeps the context alive.
+        let plugins = instrument(tailwindcss())
+
+        await build({
+          root: import.meta.dirname,
+          logLevel: 'error',
+          configFile: false,
+          build: {
+            write: false,
+            lib: { entry: 'src/main.js', formats: ['es'], fileName: 'out' },
+          },
+          plugins: [plugins],
+        })
+
+        for (let i = 0; i < 5; i++) {
+          await new Promise((resolve) => setImmediate(resolve))
+          global.gc()
+        }
+
+        console.log('plugins=' + plugins.length)
+        console.log('probeRan=' + probeRan)
+        console.log('pluginContextAlive=' + (ctxRef?.deref() !== undefined))
+      `,
+    },
+  },
+  async ({ exec, expect }) => {
+    let output = await exec('node --expose-gc probe.mjs')
+    expect(output).toContain('probeRan=true')
+    expect(output).toContain('pluginContextAlive=false')
+  },
+)
+
+test(
+  'does not keep the transform PluginContext alive after a watcher closes',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "type": "module",
+          "dependencies": {
+            "@tailwindcss/vite": "workspace:^",
+            "tailwindcss": "workspace:^"
+          },
+          "devDependencies": {
+            "vite": "^8"
+          }
+        }
+      `,
+      'src/app.css': css`@import 'tailwindcss';`,
+      'src/main.js': js`import './app.css'`,
+      'probe.mjs': js`
+        import { build } from 'vite'
+        import tailwindcss from '@tailwindcss/vite'
+
+        const NAME = '@tailwindcss/vite:generate:build'
+
+        let ctxRef = null
+        let probeRan = false
+
+        function instrument(plugins) {
+          return plugins.map((plugin) => {
+            if (plugin.name !== NAME) return plugin
+            let original = plugin.transform.handler
+            return {
+              ...plugin,
+              transform: {
+                ...plugin.transform,
+                handler(...args) {
+                  ctxRef ??= new WeakRef(this)
+                  probeRan = true
+                  return original.apply(this, args)
+                },
+              },
+            }
+          })
+        }
+
+        // Keep the plugins reachable so only the plugin's own cache can be
+        // what keeps the context alive.
+        let plugins = instrument(tailwindcss())
+
+        let watcher = await build({
+          root: import.meta.dirname,
+          logLevel: 'error',
+          configFile: false,
+          build: {
+            write: false,
+            watch: {},
+            lib: { entry: 'src/main.js', formats: ['es'], fileName: 'out' },
+          },
+          plugins: [plugins],
+        })
+
+        await new Promise((resolve, reject) => {
+          watcher.on('event', (event) => {
+            if (event.code === 'BUNDLE_END') {
+              event.result.close()
+              resolve()
+            } else if (event.code === 'ERROR') {
+              event.result?.close()
+              watcher.close().then(() => reject(event.error))
+            }
+          })
+        })
+        await watcher.close()
+
+        for (let i = 0; i < 5; i++) {
+          await new Promise((resolve) => setImmediate(resolve))
+          global.gc()
+        }
+
+        console.log('plugins=' + plugins.length)
+        console.log('probeRan=' + probeRan)
+        console.log('pluginContextAlive=' + (ctxRef?.deref() !== undefined))
+      `,
+    },
+  },
+  async ({ exec, expect }) => {
+    let output = await exec('node --expose-gc probe.mjs')
+    expect(output).toContain('probeRan=true')
+    expect(output).toContain('pluginContextAlive=false')
+  },
+)

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

@@ -282,6 +282,26 @@ export default function tailwindcss(opts: PluginOptions = {}): Plugin[] {
           return result
         },
       },
+
+      closeBundle() {
+        // In `--watch` mode, `closeBundle` fires after every rebuild, not
+        // just once at the end — clearing the roots here would throw away
+        // the mtime-based rebuild cache `Root` relies on and force a full
+        // recompile on every change. Only clear once the build itself is
+        // done for good.
+        if (this.meta.watchMode) return
+
+        // Roots hold on to the compiler (and, through it, the `PluginContext`
+        // of whichever transform call created it) for the lifetime of the
+        // plugin instance. Drop them once the bundle is done so a long-lived
+        // process (e.g. Astro's SSR build followed by static route
+        // generation) doesn't keep the finished build's context alive.
+        rootsByEnv.delete(this.environment?.name ?? 'default')
+      },
+
+      closeWatcher() {
+        rootsByEnv.delete(this.environment?.name ?? 'default')
+      },
     },
   ] satisfies Plugin[]
 }