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 / postcss-plugin

PostCSS plugin

The PostCSS plugin connects Tailwind CSS to any PostCSS host. It accepts a PostCSS tree, resolves the CSS and source files that shape the result, generates the needed Tailwind CSS, and returns the transformed tree with dependency messages for later rebuilds. It is one surface of the wider build tool integration model and uses the shared Node API and compilation services.

Integration boundary

The PostCSS surface keeps PostCSS responsible for parsing and running the plugin chain. The Tailwind plugin is responsible for turning Tailwind CSS rules into generated CSS and for telling the host which files and directories can change that result.

Plugin entrypoint

The @tailwindcss/postcss package exports a PostCSS plugin creator. A PostCSS configuration can load it as a named plugin or call it in a plugin list. The package also exposes a CommonJS entry path so PostCSS configuration can use either CommonJS or ESM module loading. packages/…/index.ts• L73-88

Using tailwindcss itself as the PostCSS plugin is no longer supported. The core package raises a clear migration error that points the host to @tailwindcss/postcss, and the integration checks this behavior for string, ESM, and CommonJS PostCSS configurations. packages/…/index.ts• L867-870

References: packages/…/index.ts• L73-88 packages/…/index.cts• L1-7 packages/…/index.ts• L867-870 integrations/…/core-as-postcss-plugin.test.ts• L4-55

Plugin options

The plugin options set the search base, output optimization, and ownership of asset URL rewriting. The defaults fit a normal PostCSS project: source scanning starts at the current working directory, optimization follows production NODE_ENV, and the plugin rewrites asset URLs unless the host already owns that work. packages/…/index.ts• L52-76

OptionPurposeDefault
baseSets the directory used for source discovery and relative paths.Current working directory
optimizeEnables or disables output optimization. An object can keep optimization while controlling minification.Enabled when NODE_ENV is production
transformAssetUrlsSelects whether this plugin rewrites relative asset URLs in loaded CSS.true

The base option is separate from the CSS file path. The CSS file identifies the PostCSS input and its import context. The base identifies the project area in which automatic source discovery takes place. packages/…/README.md• L40-55

References: packages/…/index.ts• L52-76 packages/…/README.md• L40-55 packages/…/README.md• L58-109

Source handling

Source handling connects CSS directives to the files that supply class candidates and design input. The plugin gives the shared compiler the CSS file's location, the configured base, and the source rules found in the CSS tree.

CSS source directives

Tailwind directives in the PostCSS tree control which parts of the system are active. Imports can load Tailwind entry points or other CSS. @source adds or removes scan paths. source(none) disables automatic source detection for an import. @config and @plugin connect legacy configuration or plugin modules to the CSS build. integrations/…/source.test.ts• L26-51

Relative paths in @source, @plugin, and @config are interpreted from the file where the rule appears. When another PostCSS plugin has already expanded an import, the PostCSS adapter normalizes those paths against the original rule location before Tailwind processes them. This keeps an imported CSS file's source and module references tied to that file rather than to the top-level CSS root. packages/…/index.ts• L8-72

References: packages/…/index.ts• L8-72 integrations/…/source.test.ts• L26-51 integrations/…/config.test.ts• L17-43 integrations/…/plugins.test.ts• L28-32

Candidate scanning

Candidate scanning reads the configured source set and finds class names that can produce utility CSS. With automatic detection, the scanner starts at the base directory or the compiler's configured root. Explicit source rules can add other projects or file patterns, include paths normally ignored by automatic detection, or exclude paths from the scan. packages/…/index.ts• L223-247

The plugin does not scan when the compiler reports that no utility feature is active. It also returns early when the input has no Tailwind-related at-rules. This lets ordinary CSS pass through without a scan or generated utility output. packages/@tailwindcss-postcss/src/index.ts#L97-L117, packages/@tailwindcss-postcss/src/index.ts#L158-L162

References: packages/…/index.ts• L97-117 packages/…/index.ts• L223-247 integrations/…/source.test.ts• L534-626

CSS transformation

CSS transformation replaces the Tailwind parts of the input tree while leaving the PostCSS host in control of the surrounding plugin chain. The plugin runs in the Once stage, so a plugin before it sees the source tree and a plugin after it sees the generated CSS. packages/…/index.ts• L86-88

The transformation has this shape:

flowchart LR
    A[PostCSS root] --> B[Normalize imported-rule paths]
    B --> C[Compile Tailwind CSS]
    C --> D[Find source roots and files]
    D --> E[Scan class candidates]
    E --> F[Build Tailwind CSS]
    F --> G{Optimize?}
    G -->|Yes| H[Optimized PostCSS tree]
    G -->|No| I[Generated PostCSS tree]
    H --> J[PostCSS host]
    I --> J

Compiler and tree conversion

The plugin converts the incoming PostCSS tree to the shared Tailwind CSS representation before it creates a compiler. After the compiler builds the result, the adapter converts that result back to a PostCSS tree and replaces the root's nodes. Source locations are carried across the conversion so downstream PostCSS consumers can still relate generated nodes to their input. packages/@tailwindcss-postcss/src/index.ts#L134-L149, packages/@tailwindcss-postcss/src/index.ts#L323-L343, packages/@tailwindcss-postcss/src/ast.ts#L9-L24, packages/@tailwindcss-postcss/src/ast.ts#L126-L142

The shared compiler resolves imported stylesheets and JavaScript modules through the Node service. Those loads become part of the CSS build input. A stylesheet can also have its relative asset URLs rewritten before the compiler uses its content. packages/@tailwindcss-node/src/compile.ts#L33-L63, packages/@tailwindcss-node/src/compile.ts#L158-L175

References: packages/…/index.ts• L134-149 packages/…/index.ts• L323-343 packages/…/ast.ts• L9-24 packages/…/ast.ts• L126-142 packages/…/compile.ts• L33-63

Output modes

Without optimization, the adapter converts the generated Tailwind tree directly to PostCSS nodes. With optimization, it first serializes the generated CSS, passes it through the CSS optimizer, and parses the optimized result back into PostCSS nodes. This preserves the same PostCSS output boundary in both modes. packages/…/index.ts• L303-337

The plugin caches the compiler, scanner, and converted output for each input and option set. A later build can reuse that state when its inputs remain valid. A CSS input change or a changed compiler dependency causes a full rebuild, while candidate scanning and CSS generation can then continue from the refreshed state. packages/@tailwindcss-postcss/src/index.ts#L21-L49, packages/@tailwindcss-postcss/src/index.ts#L164-L221

References: packages/…/index.ts• L21-49 packages/…/index.ts• L164-221 packages/…/index.ts• L299-343 packages/…/README.md• L58-88

Dependency messages

Dependency messages are the PostCSS-specific watch contract. The plugin adds messages to the current PostCSS result so a host such as PostCSS CLI or a framework can rebuild when a file or source area changes.

File dependencies

File dependency messages identify concrete inputs that can change the generated CSS. They cover imported stylesheets, files found by source scanning, and files recorded while loading configuration or plugin modules. The message includes the absolute file path, the current CSS input as its parent, and the plugin name. packages/@tailwindcss-postcss/src/index.ts#L166-L197, packages/@tailwindcss-postcss/src/index.ts#L249-L265

The Node loader reports a complete local JavaScript module tree for relative configuration and plugin imports. This means a change in a helper module can invalidate the CSS build even when the top-level config file did not change. packages/@tailwindcss-node/src/compile.ts#L118-L155, packages/@tailwindcss-node/src/get-module-dependencies.ts#L51-L105

References: packages/…/index.ts• L166-197 packages/…/index.ts• L249-265 packages/…/compile.ts• L118-175 packages/…/get-module-dependencies.ts• L51-105

Directory dependencies

Directory dependency messages describe positive source globs. They let a host watch a directory with a pattern instead of treating every possible file as a separate dependency. The scanner's direct files and globs are both reported, so existing files and newly created matching files can affect later output. packages/…/index.ts• L267-295

The adapter skips a redundant base-directory message in the case that can make Next.js watch its own output and start a loop. This is an integration-specific guard: the dependency message must describe the source boundary without making generated output look like new source input. packages/@tailwindcss-postcss/src/index.ts#L271-L277, integrations/postcss/next.test.ts#L360-L484

References: packages/…/index.ts• L267-295 integrations/…/source.test.ts• L391-530 integrations/…/next.test.ts• L360-484

Rebuild invalidation

The plugin checks the modification time of the input CSS and every reported dependency. It also compares the CSS text itself because another tool can generate the input in memory without changing the input file's modification time. A changed or missing input selects a full rebuild so the compiler and scanner do not use stale CSS or source rules. packages/@tailwindcss-postcss/src/index.ts#L178-L221, packages/@tailwindcss-postcss/src/index.test.ts#L459-L494

When a configuration or plugin load fails, the plugin clears the compiler state and keeps the dependency messages collected so far. It reports the error through the PostCSS root after logging it, which allows the host to retain the watch boundary for a later correction. packages/…/index.ts• L346-369

References: packages/…/index.ts• L178-221 packages/…/index.ts• L346-369 packages/…/index.test.ts• L459-494

Integration relationships

The PostCSS plugin is useful when a host already owns a PostCSS pipeline. It shares compilation and dependency concepts with the Vite plugin, but reports them as PostCSS messages rather than Vite watcher calls. The Webpack and Turbopack adapters use the same broad input model while mapping dependencies to loader APIs.

The main boundary to keep clear is asset URL ownership. The PostCSS plugin rewrites relative URLs by default because it resolves imported CSS itself. If the surrounding bundler already rewrites those URLs, set transformAssetUrls: false so one URL is not changed twice. packages/…/README.md• L91-109

References: packages/…/README.md• L91-109 packages/…/compile.ts• L47-63 packages/…/index.ts• L73-84

Change checklist

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

  • Keep the package export paths and the CommonJS compatibility entry aligned with the loading forms supported by postcss-load-config.
  • Keep the plugin option defaults aligned with PostCSS host behavior. In particular, check production detection, minification, and asset URL ownership together.
  • Keep path normalization aligned with the rule location after postcss-import or another import plugin expands the PostCSS tree.
  • Keep compiler dependency callbacks mapped to both file messages and directory messages. Missing either side can leave watch mode stale.
  • Keep the early-bail feature list aligned with the Tailwind at-rules that can change output.
  • Keep CSS-tree conversion source locations valid for downstream PostCSS plugins and source-map consumers.
  • Keep full-rebuild invalidation aware of both disk modification times and generated in-memory CSS input.
  • Keep dependency filtering from including the input CSS or generated framework output as a watched source.

Important failure modes

TriggerConsequenceGuard
The project registers tailwindcss instead of @tailwindcss/postcss.PostCSS stops with the migration error and generates no Tailwind CSS.Use the dedicated PostCSS package in the PostCSS configuration.
base points at the wrong project area.Automatic scanning misses class candidates or scans unrelated files.Set base to the directory that owns the source files, then use @source for other roots.
A relative @source, @plugin, or @config path is resolved from the top-level CSS file after import expansion.An imported stylesheet can load the wrong source or module path.Run the relative-path normalization step before Tailwind compilation.
A scanned file or source glob is not emitted as a PostCSS dependency message.Watch mode does not rebuild when a class is added or a matching file is created.Report scanner files as file dependencies and scanner globs as directory dependencies.
A local config helper changes while its module cache remains active.A rebuild uses old theme or plugin values.Invalidate recorded module paths before recreating the compiler.
The host and plugin both rewrite asset URLs.Relative URLs can point to the wrong asset after two path changes.Choose one URL rewriter and disable transformAssetUrls on the other.
The PostCSS input is generated in memory while its file timestamp stays unchanged.A new Tailwind rule is missed on the next build.Compare the current CSS text with the cached input as well as checking file times.

Key files

FileWhy to read it
packages/…/index.tsPrimary PostCSS entrypoint, options, source scanning, transformation, caching, and dependency messages.
packages/@tailwindcss-postcss/src/index.ctsCommonJS export path used for PostCSS configuration compatibility.
packages/…/index.tsPath boundary for imported @source, @plugin, and @config rules.
packages/…/ast.tsTranslation boundary between PostCSS trees and the shared Tailwind CSS tree.
packages/…/README.mdPublic options for source base, optimization, minification, and asset URL rewriting.
packages/…/compile.tsShared loading boundary for CSS, JavaScript modules, dependencies, and asset URLs.
packages/…/get-module-dependencies.tsRecursive local-module dependency behavior used for rebuild messages.
integrations/…/source.test.tsProduct-level source detection, explicit source rules, exclusions, and watch behavior.
integrations/…/config.test.tsCommonJS, ESM, and watch-mode configuration behavior.
integrations/…/next.test.tsFramework-specific dependency behavior and protection against watch loops.