Vite plugin
The Vite plugin connects Tailwind CSS to Vite's serve and build pipelines. It turns CSS entry files into generated Tailwind CSS, keeps the files that shape that CSS under watch, and reuses compiler state during development. The plugin is part of the wider build tool integration layer and shares compiler services with the Node API and compilation services.
Plugin lifecycle
The plugin runs as a group of Vite hooks. Vite first supplies the resolved project settings. The plugin then handles CSS transforms in serve or build mode. Each CSS root gets its own compiler state so separate Vite environments do not share compiler data. Build environments can still share candidate scans.
The lifecycle has this shape:
flowchart LR
A[Vite resolves configuration] --> B[Plugin records mode and CSS options]
B --> C[Vite starts a build or requests a CSS transform]
C --> D[Plugin finds or creates a CSS root]
D --> E[Compiler loads styles and modules]
E --> F[Scanner finds or reuses class candidates]
F --> G[Generated CSS returns to Vite]
G --> H[Vite serves or bundles the result]
Configuration resolution
The configuration hook records the resolved Vite settings before any CSS transform runs. It uses build mode to choose serve or build behavior. It also combines the plugin's optimization option with Vite's CSS minify setting. For server-side rendering (SSR), it records the build context so module resolution uses the matching Vite environment.
References: packages/…/index.ts• L185-205
Environment state
The plugin keeps a separate CSS root map for each Vite environment. A CSS root is the state for one CSS entry file. This separation gives client and SSR processing their own resolver context while the same plugin works with older and newer Vite APIs.
References: packages/…/index.ts• L67-75 packages/…/index.ts• L77-176 packages/…/index.ts• L226-231
CSS transformation
CSS transformation is the plugin's main Vite-facing operation. It accepts CSS roots before normal Vite CSS work, compiles Tailwind directives and sources, and returns CSS with an optional source map. Serve and build use the same generation model. Build mode can add a final optimization step.
CSS root selection
The transform hooks accept normal .css files, CSS language blocks, and Vite inline-style CSS entries. They skip Vite internal files, worker and asset queries, and CommonJS proxy modules. This boundary keeps static resources and Vite bookkeeping out of Tailwind generation.
References: packages/…/index.ts• L18-20 packages/…/index.ts• L208-241 packages/…/index.ts• L265-273 packages/…/index.ts• L315-331
Serve generation
In serve mode, Vite passes a CSS root to the pre-transform hook. The plugin creates root state on first use, asks the compiler to generate CSS, and registers the files that affect the result with Vite's watcher. If the file is not a Tailwind root, the plugin returns control without changing the CSS.
References: packages/…/index.ts• L208-241 packages/…/index.ts• L392-403 packages/…/index.ts• L461-464
Build generation
In build mode, the plugin follows the same root and dependency process. It then optimizes the generated CSS when optimization is enabled. Builds optimize by default. The optimize option can disable optimization or can keep optimization while disabling minification.
References: packages/…/index.ts• L22-27 packages/…/index.ts• L191-204 packages/…/index.ts• L245-309
Build environment scans
Build environments can share candidate scans so the same source files are scanned only once. When a reused builder starts an environment for a later build, the shared scan state resets. This lets later builds see changed source files without mixing one environment's output into another.
References: packages/…/index.ts• L69-71 packages/…/index.ts• L250-263 packages/…/index.ts• L285-292 packages/…/index.ts• L482-509
Module loading
The plugin does not use a separate Vite hook to rewrite JavaScript modules. Instead, the Tailwind compiler loads JavaScript modules and stylesheets referenced by CSS. The plugin supplies resolvers so those loads follow the project's aliases, conditions, extensions, and SSR rules.
JavaScript module resolution
JavaScript modules can provide configuration or plugin behavior needed by the CSS compiler. The compiler reports the local files it loads as dependencies. Changes inside that module tree can therefore trigger a CSS rebuild instead of affecting only the top-level module.
References: packages/…/index.ts• L77-166 packages/…/index.ts• L446-457
Stylesheet resolution
Stylesheet loads use CSS-aware resolution and become compiler dependencies. The compiler can rewrite URLs relative to the project root before it returns the stylesheet content. Imported CSS and its assets can then participate in the same Vite-managed result.
References: packages/…/index.ts• L80-110 packages/…/index.ts• L141-165 packages/…/index.ts• L446-457
Dependency invalidation
Dependency invalidation keeps generated CSS aligned with the files that define it. During compilation, the plugin records imported stylesheets, local JavaScript module trees, and explicit source paths. It passes those files and source globs to Vite's watcher. A later change can then trigger the relevant CSS transform.
The dependency path is:
sequenceDiagram
participant CSS as CSS root
participant C as Tailwind compiler
participant V as Vite watcher
participant R as Root state
CSS->>C: Load imports and source rules
C->>R: Record build dependencies
R->>V: Watch files and source globs
V->>CSS: Report a changed dependency
CSS->>R: Check dependency timestamps
R-->>C: Rebuild compiler when needed
Build dependencies
A build dependency is a file whose contents can change the compiled CSS. The root stores its last modification time. Before a rebuild, it clears the module cache when a dependency changes, disappears, or has no usable timestamp. Vite already treats the CSS input as a dependency, so the plugin does not watch it twice.
References: packages/…/index.ts• L358-379 packages/…/index.ts• L404-424 packages/…/index.ts• L427-457 packages/…/index.ts• L582-603
Source watch registration
Explicit source files and positive source globs are registered with Vite after the scanner is created. The plugin validates a configured source directory before it accepts the source rule. It also skips SVG paths with query or hash characters because those paths can break Vite's update handling.
References: packages/…/index.ts• L406-425 packages/…/index.ts• L513-553
Development rebuilds
Development rebuilds balance fresh output with retained state. A root keeps its compiler, scanner, and candidate set between transforms. A source change can reuse this setup and add new candidates. A changed CSS root or build dependency causes compiler and scanner setup to run again before CSS generation.
References: packages/…/index.ts• L358-379 packages/…/index.ts• L427-491 packages/…/index.ts• L497-509
Framework integration
Framework integration uses Vite's normal plugin contract rather than a framework-specific Tailwind entry point. A framework adds the plugin to its Vite configuration. The plugin then uses the resolver and environment that Vite supplies.
Vite version support
The package supports Vite 5.2 and later across the supported Vite major versions. It handles the older resolver API and the newer environment API. It also supports environments outside the usual client and SSR names. This keeps the plugin usable in frameworks that wrap or replace parts of Vite's resolver.
References: packages/…/package.json• L35-41 packages/…/index.ts• L111-166
SSR and framework environments
SSR builds use an SSR-aware resolver path so CSS and JavaScript imports resolve in the same environment as the consuming framework. Source-map output follows Vite's development CSS source-map setting. Framework tooling can therefore keep its module and debug behavior while Tailwind supplies the generated CSS.
References: packages/…/index.ts• L73-75 packages/…/index.ts• L83-110 packages/…/index.ts• L168-176 packages/…/index.ts• L185-204
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the serve and build CSS filters aligned when the set of accepted Vite CSS IDs changes.
- Keep Vite's resolver behavior aligned with the compiler callbacks for CSS imports, JavaScript modules, aliases, and SSR environments.
- Preserve the dependency handoff from compiler loads and source rules to Vite's watcher. A missing handoff can leave generated CSS stale without an obvious transform error.
- Recheck cache clearing and root reuse together when changing rebuild rules. One controls fresh module contents. The other controls compiler and scanner lifetime.
- Keep shared build scans aligned with environment reset rules when changing build reuse behavior.
- Keep the
optimizeoption, Vite's CSS minify setting, and build-only optimization behavior consistent when changing CSS output controls.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A stylesheet or local module is loaded without being reported as a dependency | Changes to that file do not cause generated CSS to rebuild | Route compiler loads through the dependency callback |
| A build dependency changes or is removed but its module cache remains | A rebuild can use old configuration or plugin code | Clear the require cache before recompiling the root |
A non-directory path is used as a source(…) root | Source scanning fails instead of producing expected CSS | Validate the source root before scanner use |
| A Vite worker, asset, proxy, or internal CSS ID reaches Tailwind generation | The plugin can transform a resource that is not a Tailwind CSS root | Keep the special-query and internal-path filters active |
| A framework supplies an environment that is not handled by the resolver compatibility path | CSS or JavaScript imports resolve against the wrong project context | Use the environment resolver with the older client and SSR fallback |
| A reused build environment keeps stale shared scan results | CSS can omit candidates added since the prior build | Reset shared scans when an environment builds again |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Primary plugin lifecycle, CSS hooks, root state, dependency watching, rebuild checks, shared build scans, and Vite compatibility behavior |
| packages/…/README.md | Public plugin options for CSS optimization and minification |
| packages/…/package.json | Package boundary and supported Vite peer versions |
| packages/…/compile.ts | Shared compiler boundary for JavaScript modules, stylesheets, dependency reporting, and URL handling |
| packages/…/get-module-dependencies.ts | Recursive discovery of local JavaScript module dependencies |
| playgrounds/…/vite.config.ts | Small example of composing the plugin with a framework plugin |
See also: Build tool integrations, Node API and compilation services, PostCSS plugin, and Webpack and Turbopack adapters.