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 / build-tool-integrations

Build tool integrations

Build tool integrations connect Tailwind CSS input to the JavaScript build system that serves or ships an application. They give each build tool one shared path to compile CSS, find class candidates in source files, track files that affect the result, and rebuild only when the result can change.

Shared integration model

The integration model separates Tailwind CSS work into a compiler, a source scanner, and a build-tool boundary. The compiler reads the CSS entry point and its imports. The scanner finds class candidates in the configured source set. A plugin or the CLI build command turns those inputs into CSS output and rebuild signals for its host.

This diagram shows how a CSS entry point moves through compilation and source discovery before the build tool receives CSS and watch information.

flowchart LR
    A[CSS entry point] --> B[Shared compiler]
    B --> C[Source roots and source paths]
    C --> D[Source scanner]
    D --> E[Class candidates]
    E --> F[Generated CSS]
    B --> G[Imported CSS and JavaScript dependencies]
    F --> H[Build tool output]
    G --> I[Build tool watch graph]
    D --> I
    I --> J[Rebuild request]
    J --> B

CSS compilation

The shared compiler turns a CSS entry point into a reusable build operation. It resolves imported stylesheets and JavaScript modules, records the source rules that control scanning, and exposes a build step that adds generated utility CSS for the candidates supplied by an adapter. It also checks that an explicit source(...) root exists before the adapter starts scanning. This keeps CSS language rules and utility generation consistent across all build tools. See Node API and compilation for the shared API.

References: packages/…/index.ts• L142-167 packages/…/index.ts• L714-721 packages/…/index.ts• L824-859 packages/…/compile.ts• L66-103

Source discovery

Source discovery finds class candidates in application files so the compiler can emit only the utilities that the application uses. The CSS entry point can disable automatic discovery or define explicit roots and source paths. The adapters pass those rules to the scanner and retain the candidates across rebuilds so a new file can add CSS without losing earlier results. See Content discovery and scanning for the source model.

References: packages/…/index.ts• L107-115 packages/…/index.ts• L174-221 packages/…/index.ts• L257-305 crates/…/lib.rs• L88-133

Dependency tracking

Dependency tracking links every input that can change the generated CSS to the host watch system. This includes imported stylesheets, loaded JavaScript modules, scanned files, and source globs. A change to a compiler dependency requires the integration to reload the compiler state. A change to a scanned file requires a new scan and a CSS build. The CLI uses the same dependency split for event-based watching and polling.

References: packages/…/compile.ts• L118-177 packages/…/index.ts• L427-457 packages/…/index.ts• L164-209 packages/…/index.ts• L135-179 packages/…/index.ts• L278-325 packages/…/index.ts• L800-822

Rebuild behavior

Rebuild behavior uses a fast path when the compiler and its inputs remain valid. The adapters keep compiler and scanner state for a CSS root, compare tracked file changes and received CSS content, and choose a full rebuild when an imported file, the CSS input, or another compiler dependency changes. The CLI follows the same rule and can detect changes with native file events or polling. Errors clear or replace cached state so the next build can recover from a changed configuration or dependency.

References: packages/…/index.ts• L358-445 packages/…/index.ts• L590-602 packages/…/index.ts• L568-588 packages/…/index.ts• L119-158 packages/…/index.ts• L212-243 packages/…/index.ts• L93-183 packages/…/index.ts• L279-285 packages/…/index.ts• L330-483 packages/…/index.ts• L522-663

Build tool surfaces

Each supported surface owns the boundary between the shared compiler and a build tool. The boundary changes how CSS enters the system, how dependencies are reported, and how development or production rebuilds are requested. The result should remain the same: source files produce candidates, candidates produce CSS, and relevant changes produce a new result.

SurfaceBuild tool boundaryIntegration role
Node API and compilationDirect JavaScript or Node useProvides compilation, module and stylesheet loading, dependency callbacks, source maps, and optimization to other tools.
CLI build workflowCommand-line build and watch modesRuns the shared compiler and scanner directly, writes CSS and source maps, and supports event-based or polling rebuilds.
Vite pluginVite plugin hooksProcesses CSS roots in serve and build modes, uses Vite resolution, shares source scans across build environments, and reports files and globs to Vite's watcher.
PostCSS pluginPostCSS processingTransforms a PostCSS tree, reports file and directory dependencies, and can optimize or rewrite asset URLs.
Webpack and Turbopack adaptersLoader APIsProcesses CSS as a loader result, registers file and context dependencies, and returns CSS to webpack-compatible pipelines.

Node API boundary

The Node API is the shared boundary for JavaScript tools that need to run Tailwind CSS without choosing one build tool surface. It supplies the compiler with module and stylesheet loading, lets callers receive dependency paths, and exposes related services such as optimization, source maps, and CSS URL rewriting. Its compile entry points also reject a missing explicit source root before scanning begins. Its CommonJS and ESM entry points install the runtime support needed to reload imported modules during watch rebuilds. The plugin surfaces use this boundary rather than defining separate CSS compilation rules.

References: packages/…/index.ts• L5-28 packages/…/index.cts• L5-27 packages/…/compile.ts• L22-31 packages/…/compile.ts• L66-118

CLI build boundary

The CLI build boundary gives users a direct command-line path through the shared compiler and scanner. It accepts a CSS input or a default Tailwind entry point, writes CSS to a file or standard output, and can add source maps and output optimization. Its watch modes keep the compiler state alive and choose between incremental candidate scans and full compiler recreation when a CSS or configuration dependency changes. See CLI build workflow for the command workflow.

References: packages/…/index.ts• L125-325 packages/…/index.ts• L330-483 packages/…/index.ts• L502-570 packages/…/index.ts• L604-663

Vite plugin boundary

The Vite surface treats each relevant CSS resource as a Tailwind CSS root. It runs in both serve and build modes and keeps root state separate for each Vite environment. During a build, environments can share scans of the same source set so later environments do not scan earlier build output. The plugin uses Vite's resolver so aliases and framework-specific paths remain visible, and sends discovered files and globs to Vite for watch updates. It also compares the CSS content passed by earlier plugins, so an in-memory change can trigger a new compiler setup even when file times do not change. The published plugin supports Vite 5 through Vite 8. Build mode can also optimize the generated CSS. See Vite plugin for its tool-specific contract.

References: packages/…/index.ts• L67-176 packages/…/index.ts• L179-309 packages/…/index.ts• L358-470 packages/…/index.ts• L483-545 packages/…/index.ts• L590-602 packages/…/package.json• L24-41

PostCSS plugin boundary

The PostCSS surface accepts a PostCSS tree and replaces the Tailwind parts with generated CSS while preserving the surrounding PostCSS flow. It reports direct file dependencies and directory patterns as PostCSS messages, which lets PostCSS hosts rebuild when source content or imported configuration changes. The published plugin supports both import and require consumers. It also owns optional output optimization and asset URL rewriting for this surface. See PostCSS plugin for its tool-specific contract.

References: packages/…/index.ts• L73-117 packages/…/index.ts• L155-209 packages/…/index.ts• L245-345 packages/…/package.json• L25-35

Webpack and Turbopack loader boundaries

The webpack and Turbopack surfaces use the same loader shape and shared build flow. They register scanned files as direct dependencies and source patterns as context dependencies, then return generated CSS to the loader pipeline. The loader compares both tracked file times and the CSS content it receives, so changes from an earlier loader can force a full compiler rebuild even when the source file time is unchanged. Their separate adapters let each tool own its loader contract while keeping candidate discovery, compilation, rebuild checks, and optimization aligned. See Webpack and Turbopack adapters for the loader details.

References: packages/…/index.ts• L61-71 packages/…/index.ts• L135-179 packages/…/index.ts• L186-278 packages/…/index.ts• L61-71 packages/…/index.ts• L186-278

Integration lifecycle

The lifecycle is the same across surfaces even though each build tool has a different hook or loader API. The adapter creates shared state for a CSS root, compiles the input, discovers candidates, registers dependencies, builds CSS, and then repeats the smallest valid part of that work after a change.

When a build tool processes a CSS root, it follows this sequence:

  1. Receive CSS and determine the root and build options.
  2. Compile the CSS and resolve its imported CSS and JavaScript resources.
  3. Create or update the scanner from automatic and explicit source rules.
  4. Scan source files for class candidates when utilities are enabled.
  5. Register files and source patterns with the build tool's watch graph.
  6. Build CSS from the candidates and optionally optimize the result.
  7. Reuse or rebuild shared state when a watched input changes.

Root state

Root state represents one CSS entry point and its current view of the compiler, scanner, candidates, and build dependencies. Keeping this state across tool calls allows development builds to add candidates over time and avoid repeating setup work when no tracked input changed. Vite groups this state by build environment and can share candidate scans across environments during one build. The CLI keeps equivalent compiler and scanner state while it watches one command's input set.

References: packages/…/index.ts• L67-71 packages/…/index.ts• L250-263 packages/…/index.ts• L358-374 packages/…/index.ts• L21-49 packages/…/index.ts• L33-59 packages/…/index.ts• L196-200 packages/…/index.ts• L327-328

Output optimization

Output optimization is a shared post-processing step applied after Tailwind CSS generates the result. The Node optimizer can reduce output size, apply selected CSS compatibility transforms for supported browser targets, and preserve a source map when the caller provides one. It runs the transform in two passes so changes such as nesting can be followed by further rule reduction. The integrations normally enable it for production builds and allow callers to disable it or keep optimization while disabling minification.

References: packages/…/optimize.ts• L29-60 packages/…/optimize.ts• L78-139 packages/…/index.ts• L191-204 packages/…/index.ts• L299-305 packages/…/index.ts• L303-325 packages/…/index.ts• L266-275

Asset URL ownership

Asset URL ownership prevents two tools from rewriting the same CSS URL. The shared Node compiler can rewrite relative URLs in declarations and image sets while leaving absolute, external, data, fragment, variable, and function-based values unchanged. The PostCSS surface exposes a switch because some hosts already provide this behavior. A surface must make one owner clear before it passes CSS to the next stage.

References: packages/…/urls.ts• L37-113 packages/…/urls.ts• L122-181 packages/…/urls.test.ts• L6-174 packages/…/compile.ts• L47-62 packages/…/index.ts• L52-76 packages/…/index.ts• L1-20

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to compiler feature detection in packages/…/index.ts must keep each adapter's early-bail rules aligned with the features that can affect output.
  • Changes to root or sources must preserve the mapping from source rules to scanner inputs and then to the build tool's file or glob dependency API.
  • Changes to source-root validation must keep explicit source(...) paths checked against the correct base before the scanner runs.
  • Changes to module or stylesheet loading must keep dependency callbacks complete so imported config, plugins, stylesheets, and their own dependencies trigger a full rebuild.
  • Changes to candidate retention or scanner output must preserve the rule that rebuilds do not remove valid candidates unless the adapter performs a full state reset.
  • Changes to Vite environment sharing must keep shared candidate scans scoped to one build and clear them when a reused environment starts a new build.
  • Changes to adapter input tracking must keep in-memory CSS changes visible even when the source file timestamp is unchanged.
  • Changes to URL rewriting must define whether the Node compiler, PostCSS, or the host build tool owns the rewrite.
  • Changes to URL parsing or rebasing must preserve the distinction between local asset paths and URLs that the host must resolve.
  • Changes to optimization defaults must stay consistent with the build tool's production mode and its minification setting.
  • Changes to CSS compatibility targets or transform behavior in packages/…/optimize.ts must remain compatible with the CSS emitted by every surface and with its source-map path.
  • Changes to CSS source-map support must keep the from path and returned map aligned with the adapter that consumes the CSS.
  • Changes to CLI watch handling must keep full-rebuild dependencies separate from scanned files, and must preserve recovery after a broken dependency is restored.
  • Changes to CLI watcher setup must keep event and polling modes from watching the output or source-map files as build inputs.

Important failure modes

TriggerConsequenceGuard
An explicit source(...) root does not exist.The build cannot scan the configured source tree.Validate the non-glob part of the source path against the compiler base before scanning.
A CSS import or loaded module is not reported as a dependency.A change to theme, plugin, or imported CSS input does not trigger a full rebuild.Route every resolved stylesheet and module dependency through the surface's dependency callback or message API.
A source root or @source path maps to the wrong base or pattern.The scanner misses application files or watches the wrong directory.Validate source paths and pass the compiler's source entries to the scanner without changing their meaning.
A scanned file or glob is not registered with the host watcher.New or changed class names do not appear until a manual restart.Register both direct files and positive source globs with the build tool's dependency model.
A full rebuild reuses stale module state.Updated config or plugin code has no effect, or an old error remains.Clear the recorded module cache paths before recreating compiler state.
The CLI treats a compiler dependency as an incremental source change.A theme, plugin, or imported CSS change does not recreate compiler state.Compare changed paths with the recorded full-rebuild paths before choosing the incremental scan.
The CLI watches its own output or source map.Each write can trigger another rebuild loop.Exclude the configured output and map paths from watch change handling.
A reused Vite build shares a scan after its source set changed.An environment can emit CSS from stale candidates.Reset shared Vite scan state when a previously built environment starts again.
An earlier build step changes CSS in memory but the adapter checks only file times.The compiler keeps stale imports, plugins, or CSS rules.Compare the received CSS content with the last compiler input and force a full setup when it differs.
The host and an integration both rewrite asset URLs.Relative asset paths can be changed twice and point to the wrong file.Select one URL rewriter and disable the other surface's rewrite option.
The input uses no Tailwind feature but the adapter still handles it.Unrelated CSS is changed or receives needless scan and build work.Keep feature checks and quick-bail checks in step with the compiler's feature set.

Key files

FileWhy to read it
packages/…/index.tsDefines the shared compilation contract, source rules, feature signals, and reusable CSS build operation.
packages/…/index.tsShows the ESM Node entry point and the shared services exposed to build tool adapters.
packages/@tailwindcss-node/src/index.ctsShows the CommonJS Node entry point and its equivalent module reload support.
packages/…/compile.tsConnects the compiler to Node module and stylesheet loading, source-root validation, dependency reporting, URL handling, and source-map input.
packages/…/get-module-dependencies.tsShows how relative module dependencies are traced so watch systems can reload related files.
packages/…/urls.tsDefines the shared contract for rebasing local CSS asset URLs.
packages/…/urls.test.tsShows the URL rewrite cases that the shared Node boundary must preserve.
packages/…/optimize.tsDefines the shared post-processing contract for CSS reduction, compatibility transforms, warnings, and source maps.
crates/…/lib.rsDefines the scanner boundary used by JavaScript integrations for source entries, candidate scans, files, and globs.
packages/…/index.tsShows the direct compiler and scanner workflow, output handling, and full versus incremental watch rebuilds.
packages/…/index.tsShows how a Vite plugin maps serve and build hooks to shared compilation, environment-scoped scanning, in-memory input tracking, watching, and optimization.
packages/…/package.jsonDefines the published Vite plugin entry point and supported Vite peer range.
packages/…/index.tsShows how a PostCSS host receives generated CSS and dependency messages while retaining PostCSS processing.
packages/…/package.jsonDefines the published PostCSS entry points for import and require consumers.
packages/…/index.tsShows the webpack loader contract, its file and context dependency model, and its input-content rebuild check.
packages/…/index.tsShows the Turbopack loader boundary and its alignment with the webpack-style adapter flow.