Introducing a new way to review your PRs.

Read the announcement

tailwindlabs / tailwindcss

A utility-first CSS framework for rapid UI development.

View on GitHub

19 documents · Updated Nov 20, 2026

docs / vite-plugin

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 optimize option, Vite's CSS minify setting, and build-only optimization behavior consistent when changing CSS output controls.

Important failure modes

TriggerConsequenceGuard
A stylesheet or local module is loaded without being reported as a dependencyChanges to that file do not cause generated CSS to rebuildRoute compiler loads through the dependency callback
A build dependency changes or is removed but its module cache remainsA rebuild can use old configuration or plugin codeClear the require cache before recompiling the root
A non-directory path is used as a source(…) rootSource scanning fails instead of producing expected CSSValidate the source root before scanner use
A Vite worker, asset, proxy, or internal CSS ID reaches Tailwind generationThe plugin can transform a resource that is not a Tailwind CSS rootKeep the special-query and internal-path filters active
A framework supplies an environment that is not handled by the resolver compatibility pathCSS or JavaScript imports resolve against the wrong project contextUse the environment resolver with the older client and SSR fallback
A reused build environment keeps stale shared scan resultsCSS can omit candidates added since the prior buildReset shared scans when an environment builds again

Key files

FileWhy to read it
packages/…/index.tsPrimary plugin lifecycle, CSS hooks, root state, dependency watching, rebuild checks, shared build scans, and Vite compatibility behavior
packages/…/README.mdPublic plugin options for CSS optimization and minification
packages/…/package.jsonPackage boundary and supported Vite peer versions
packages/…/compile.tsShared compiler boundary for JavaScript modules, stylesheets, dependency reporting, and URL handling
packages/…/get-module-dependencies.tsRecursive discovery of local JavaScript module dependencies
playgrounds/…/vite.config.tsSmall 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.