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 / webpack-and-turbopack-adapters

Webpack and Turbopack adapters

The Webpack and Turbopack adapters connect Tailwind CSS to loader-based build pipelines. They accept a CSS resource, use shared Node compilation services and the native scanner to produce Tailwind CSS, and report the inputs that can affect that result to the host build tool. They form two build-tool boundaries in the wider build tool integration model.

Adapter boundaries

Each package presents Tailwind CSS as a loader in a CSS pipeline. The build tool schedules the resource, while the adapter handles Tailwind compilation, candidate discovery, dependency reporting, and the CSS result.

This diagram shows the common path from a loader request to CSS and watch dependencies.

flowchart LR
    A[CSS loader request] --> B[Adapter state]
    B --> C[Shared Tailwind compiler]
    C --> D[Source rules]
    D --> E[Native source scanner]
    E --> F[Class candidates]
    F --> G[Generated CSS]
    C --> H[Imported styles and modules]
    E --> I[Scanned files and source globs]
    G --> J[Loader result]
    H --> K[Build-tool dependencies]
    I --> K

Webpack adapter

The Webpack adapter is the @tailwindcss/webpack loader. Webpack passes a CSS resource and loader options to it. The adapter returns generated CSS through the loader callback and registers files and directories through the host dependency APIs. packages/…/index.ts• L61-71

The package also supports the Webpack-compatible Rspack peer boundary. Its public options set the source scan base and output optimization. The base defaults to the current working directory, while optimization follows production mode unless the caller sets it. packages/…/package.json• L24-53

References: packages/…/index.ts• L61-71 packages/…/index.cts• L1-5 packages/…/package.json• L24-53 packages/…/README.md• L40-101

Turbopack adapter

The Turbopack adapter is the @tailwindcss/turbopack loader. A Turbopack rule maps CSS resources to this loader, which returns generated CSS and dependency information for the surrounding pipeline. Its public options use the same base and optimization model as the Webpack adapter. packages/…/README.md• L40-99

The two adapters keep separate host package boundaries but align their Tailwind behavior. A project can therefore move between Webpack-style and Turbopack-style pipelines without changing how the CSS entry point controls source discovery or production output. packages/…/index.ts• L61-71

References: packages/…/index.ts• L61-71 packages/…/index.cts• L1-5 packages/…/package.json• L24-42 packages/…/README.md• L52-99

Shared compilation services

The adapters do not define separate Tailwind compilers. They pass CSS input to @tailwindcss/node, which resolves imported stylesheets and JavaScript modules and returns a compiler that builds CSS from discovered candidates. The native @tailwindcss/oxide scanner supplies those candidates. packages/…/index.ts• L5-10

CSS input and source rules

The CSS entry point defines the Tailwind build settings. Its Tailwind directives can select automatic scanning, set explicit source paths, or connect configuration and plugin modules. The adapter turns those source rules into scanner inputs. An unspecified root uses the configured base directory, while a disabled root produces no automatic scan. packages/…/index.ts• L97-115

CSS with no Tailwind at-rules can pass through without candidate scanning or utility generation. This lets the loader avoid Tailwind work for unrelated CSS. packages/…/index.ts• L77-88

References: packages/…/index.ts• L77-88 packages/…/index.ts• L97-129 packages/…/index.ts• L186-205 packages/…/index.ts• L77-88 packages/…/compile.ts• L22-31

Candidate discovery

Candidate discovery reads the source files selected by the compiler and finds class names that can produce utility CSS. The adapter keeps the candidates for the CSS resource and passes them to the compiler's build operation. New source files can add candidates during development. packages/…/index.ts• L208-214

The scanner reports both concrete files and source globs. The adapter uses files as direct watch entries and positive globs as directory watch entries. It validates an explicit source root as a directory before scanning it. packages/…/index.ts• L216-259

References: packages/…/index.ts• L186-205 packages/…/index.ts• L208-259 packages/…/index.ts• L186-259 crates/…/lib.rs• L88-190

Module and stylesheet loading

Imported CSS and JavaScript modules are part of the Tailwind input. The shared Node service resolves them from the importing resource, loads their content or module value, and reports paths that can affect the result. The adapters enable URL rewriting while the service loads imported stylesheets, so relative asset paths are handled before the loader returns CSS. packages/…/compile.ts• L33-63

This shared boundary keeps configuration, plugins, imported styles, and their local dependencies in the same build graph as the CSS entry point. See Node API and compilation for the service contract used by the adapters.

References: packages/…/compile.ts• L94-115 packages/…/compile.ts• L118-175 packages/…/get-module-dependencies.ts• L51-105 packages/…/index.ts• L105-114

Loader build lifecycle

The loader lifecycle combines one-time compiler setup with repeated candidate scans and CSS builds. Each CSS resource and option set gets bounded state that holds the compiler, scanner, candidate set, and dependencies needed for later requests. packages/…/index.ts• L33-59

When a loader request arrives, the adapter follows this sequence:

  1. It reads the CSS resource and loader options.
  2. It creates or reuses the shared compiler for that resource.
  3. It checks imported inputs and the CSS file to choose incremental or full work.
  4. It creates or refreshes the scanner from the compiler's source rules.
  5. It scans for candidates and registers files and source globs with the host.
  6. It builds CSS from the retained candidate set.
  7. It optionally optimizes the CSS and returns it to the loader pipeline.

This sequence shows how a changed input moves through dependency checks before the adapter chooses a full compiler rebuild or reuses current state.

flowchart TD
    A[Loader request] --> B{Tracked input changed?}
    B -->|No| C[Reuse compiler and scanner]
    B -->|CSS or compiler dependency| D[Clear module cache]
    D --> E[Create compiler and scanner]
    C --> F[Scan or retain candidates]
    E --> F
    F --> G[Build CSS]
    G --> H{Optimization enabled?}
    H -->|Yes| I[Optimized CSS]
    H -->|No| J[Generated CSS]
    I --> K[Loader result]
    J --> K

Dependency invalidation

Dependency invalidation links all CSS-shaping inputs to the host watch graph. Imported stylesheets and module dependencies become direct file dependencies. Scanned files also become direct dependencies, while source globs become context dependencies so new matching files can trigger a build. packages/…/index.ts• L134-165

The adapter compares modification times for the CSS input and compiler dependencies. A changed or missing input causes full compiler setup. That setup clears recorded module cache entries before it recreates the compiler, so changed configuration or plugin code can take effect. packages/…/index.ts• L97-123

References: packages/…/index.ts• L97-123 packages/…/index.ts• L134-169 packages/…/index.ts• L216-239 packages/…/require-cache.ts• L1-5

Error recovery

A failed loader build removes the affected cached state before it returns the error. The next request must create fresh compiler and scanner state instead of reusing a failed or partial build. packages/…/index.ts• L279-285

This recovery rule matters for configuration, plugin, and imported CSS changes. The host can report the error while a later request retries the same CSS resource with current inputs.

References: packages/…/index.ts• L279-285 packages/…/index.ts• L279-285

Output controls

The adapters build CSS through the shared compiler and then apply an optional shared optimization step. Optimization is enabled by default when Webpack runs in production mode or when NODE_ENV is production; an object option can keep optimization while controlling minification. packages/…/index.ts• L61-71

CSS Module inputs receive a different polyfill choice because global property rules can violate CSS Module purity. This keeps module output valid without changing normal global CSS behavior. packages/…/index.ts• L105-115

The PostCSS plugin has a separate asset URL ownership option because a PostCSS host may already rewrite URLs. The Webpack and Turbopack adapters always ask the shared compiler to rewrite URLs for imported stylesheets. A surrounding pipeline must not rewrite the same input a second time. packages/…/compile.ts• L47-62

References: packages/…/index.ts• L61-71 packages/…/index.ts• L105-115 packages/…/index.ts• L262-275 packages/…/index.ts• L262-275 packages/…/compile.ts• L47-62

Integration relationships

The adapters use the same compiler and scanner concepts as the Vite plugin and PostCSS plugin, but they express the host boundary through loader callbacks and dependency APIs. The Node API and compilation page explains the shared services; this page focuses on how Webpack and Turbopack connect those services to their build graphs.

Change checklist

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

  • Keep the Webpack and Turbopack loader flows aligned when compiler feature flags or source-rule meanings change.
  • Keep loader option changes in sync with cache keys. A base or optimization change must not reuse state for a different build result.
  • Preserve both direct file dependencies and positive source-glob dependencies. Missing either path can leave watch mode stale.
  • Keep compiler dependency callbacks aligned with full-rebuild checks so imported CSS, configuration, plugins, and local module helpers trigger fresh state.
  • Keep CommonJS cache clearing aligned with the module loading behavior used by the shared Node service.
  • Keep CSS Module polyfill behavior separate from global CSS behavior when changing compiler polyfills.
  • Keep URL rewriting owned by one stage. A host change must not cause imported asset paths to be rewritten twice.

Important failure modes

TriggerConsequenceGuard
A scanned file or source glob is not registered with the loader host.New or changed class names do not appear until the build restarts.Register scanner files as direct dependencies and positive globs as context dependencies.
An imported stylesheet or JavaScript dependency is not reported.A changed theme, plugin, or imported style does not trigger a full rebuild.Pass every resolved dependency through the shared compiler callback and the loader dependency API.
A changed configuration module remains in the module cache.The loader rebuilds with old theme or plugin behavior.Clear recorded module cache paths before recreating the compiler.
The scan base or explicit source root is wrong.The scanner misses candidates or reads an unrelated project area.Set the base to the source-owning directory and validate explicit roots as directories.
The host and compiler both rewrite imported asset URLs.Relative asset paths can point to the wrong file after two rewrites.Keep URL rewriting owned by one stage.
A CSS Module input receives global property polyfills.The CSS Module build can fail its purity checks.Exclude the property polyfill for CSS Module resources.
A failed build leaves its cache entry active.Later requests can reuse partial compiler or scanner state.Delete the resource's cached state when the loader reports an error.

Key files

FileWhy to read it
packages/…/index.tsPrimary Webpack loader flow for compilation, scanning, dependency registration, rebuilds, and output.
packages/…/index.tsTurbopack loader boundary and its alignment with the Webpack adapter flow.
packages/…/README.mdWebpack loader setup and public options.
packages/…/README.mdTurbopack rule setup and public options.
packages/…/compile.tsShared CSS and module compilation, dependency reporting, and URL handling.
packages/…/optimize.tsShared CSS optimization and source-map result used after generation.
packages/…/require-cache.tsCache reset used before full rebuilds.
packages/…/index.tsPublic Node service boundary consumed by both adapters.
packages/…/package.jsonWebpack package exports, public package boundary, and Webpack or Rspack peer support.
packages/…/package.jsonTurbopack package exports and package boundary.