Tailwind CSS Administrator & Developer Guide

Tailwind CSS v4.2.2 — utility-first CSS framework reimagined as a full compiler
License: MIT | Source: tailwindlabs/tailwindcss @ 5a835e1

Tailwind CSS v4 is a ground-up rewrite that replaces the JavaScript-driven PostCSS plugin architecture of v3 with a standalone CSS compiler built on a Rust extraction engine, a TypeScript AST pipeline, and first-party integrations for every major build tool. This guide covers the internal architecture, build system, configuration surface, deployment patterns, security posture, and developer workflows necessary to operate, extend, and troubleshoot Tailwind CSS at scale.

1. Architecture Overview

1.1 High-Level Data Flow

Source Files (.html, .jsx, .vue, ...)
        │
        ▼
┌─────────────────────┐
│   Oxide Scanner     │  Rust (napi-rs)
│   (crates/oxide)    │  State-machine candidate extraction
└────────┬────────────┘
         │ candidate strings
         ▼
┌─────────────────────┐
│   CSS Compiler      │  TypeScript
│   (packages/        │  Parse → Resolve → Compile → Optimize
│    tailwindcss)     │
└────────┬────────────┘
         │ CSS AST
         ▼
┌─────────────────────┐
│   Optimization      │  lightningcss
│   Minification      │  (via @tailwindcss-node)
│   Source Maps        │
└────────┬────────────┘
         │
         ▼
    Output CSS file

The compiler operates in two distinct phases:

1. Scan phase — The Rust-based oxide engine traverses source files, applies language-specific pre-processors, and runs a battery of state machines to extract candidate class strings. This is CPU-bound, parallelized via rayon, and SIMD-optimized for whitespace skipping.

2. Generate phase — The TypeScript compiler receives candidate strings, resolves them against the design system (theme values, registered utilities, registered variants), applies @apply directives, resolves @import chains, and emits a CSS AST that gets serialized and optionally optimized through lightningcss.

1.2 Monorepo Layout

The repository is a dual workspace: pnpm manages TypeScript/JavaScript packages; Cargo manages Rust crates. Turborepo (turbo) orchestrates cross-language builds.

tailwindcss/
├── packages/
│   ├── tailwindcss/              Core CSS compiler (TS)
│   ├── @tailwindcss-cli/         CLI binary
│   ├── @tailwindcss-postcss/     PostCSS plugin
│   ├── @tailwindcss-vite/        Vite plugin
│   ├── @tailwindcss-webpack/     Webpack loader
│   ├── @tailwindcss-node/        Node.js integration layer
│   ├── @tailwindcss-browser/     In-browser compiler
│   ├── @tailwindcss-standalone/  Standalone Bun-built binary
│   ├── @tailwindcss-upgrade/     v3→v4 migration tool
│   └── @tailwindcss-oxide/       N-API bindings for Rust
├── crates/
│   ├── oxide/                    Core extraction engine (Rust)
│   ├── node/                     N-API bridge (Rust)
│   ├── ignore/                   .gitignore matcher (forked from ripgrep)
│   └── classification-macros/    Proc macros for byte classification
├── integrations/                 Integration test suites
├── playgrounds/                  Dev playgrounds
└── oxide/                        Rust workspace root

1.3 Package Dependency Graph

@tailwindcss-cli ──────────┐
@tailwindcss-postcss ──────┤
@tailwindcss-vite ─────────┤
@tailwindcss-webpack ──────┤
                           ▼
                   @tailwindcss-node
                           │
                     ┌─────┴─────┐
                     ▼           ▼
              tailwindcss   @tailwindcss-oxide
                     │           │
                     │     ┌─────┘
                     ▼     ▼
              (lightningcss, enhanced-resolve,
               jiti, source-map-js)

Every build tool integration depends on @tailwindcss-node, which provides module resolution, optimization, and the bridge to the core compiler. The core tailwindcss package has zero Node.js dependencies — it is pure TypeScript operating on CSS ASTs.

1.4 Technology Stack

2. System Requirements

2.1 Build-Time Requirements

Important

The Rust toolchain is only required when building oxide from source. Published npm packages include pre-built platform binaries for 12 targets: linux-x64-gnu, linux-x64-musl, linux-arm64-gnu, linux-arm64-musl, darwin-x64, darwin-arm64, win32-x64-msvc, win32-arm64-msvc, freebsd-x64, android-arm64, android-arm-eabi, and wasm32-wasi-preview1-threads.

2.2 Runtime Requirements

For end users consuming published packages:

2.3 Platform Binary Matrix

The @tailwindcss-oxide package publishes platform-specific npm packages using the napi-rs convention:

Warning

Linux ARM64 users have reported missing native module errors when the correct platform package is not installed. This commonly occurs in Docker multi-arch builds or when using npm instead of pnpm (which handles optional dependencies differently). See GitHub issue #15806. Ensure your package manager installs optional dependencies, or use the standalone binary as a workaround.

2.4 Standalone Binary

The standalone binary (@tailwindcss/standalone) bundles the full compiler into a single executable built with Bun. It includes the official plugins (@tailwindcss/forms, @tailwindcss/typography, @tailwindcss/aspect-ratio) and requires no Node.js runtime.

Platform binaries:

• tailwindcss-linux-x64
• tailwindcss-linux-arm64
• tailwindcss-macos-x64
• tailwindcss-macos-arm64
• tailwindcss-windows-x64.exe

Module resolution in standalone mode uses globalThis.__tw_resolve and globalThis.__tw_load — custom shims that resolve against the bundled module graph rather than the filesystem.

3. Configuration Reference

3.1 CSS-First Configuration (v4 Model)

Tailwind CSS v4 replaces tailwind.config.js with CSS-native configuration. All customization happens inside your CSS file using at-rules:

@import "tailwindcss";

/* Theme customization */
@theme {
  --color-primary: #3b82f6;
  --font-sans: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

/* Source detection */
@source "../components/**/*.tsx";

/* Plugin loading */
@plugin "@tailwindcss/forms";

/* Custom variant */
@variant dark (&:where(.dark, .dark *));

3.2 CSS At-Rules Reference

Note

The @import "tailwindcss" directive is the canonical entry point. It expands to @import "tailwindcss/preflight.css", @import "tailwindcss/theme.css", and @import "tailwindcss/utilities.css". You can import these individually for granular control.

3.3 Theme Namespace Reference

Theme values are CSS custom properties organized by namespace. Each namespace maps to a set of utilities:

3.4 CSS Functions

Tailwind v4 provides CSS functions that resolve against the design system:

Caution

--spacing() requires an argument. Calling it without one produces the error: "The --spacing(...) function requires an argument" (css-functions.ts:49). Similarly, --theme() only works with CSS variables from your theme — using it with arbitrary values produces: "The --theme(...) function can only be used with CSS variables from your theme" (css-functions.ts:75).

3.5 Environment Variables

3.6 Build Tool Configuration

CLI Options

tailwindcss build [options]

Options:
  -i, --input <path>    Input CSS file (use "-" for stdin)
  -o, --output <path>   Output CSS file (use "-" for stdout)
  -w, --watch           Watch for changes and rebuild
  --minify              Minify the output CSS
  -h, --help            Show help

Commands:
  build                 Build CSS (default)
  canonicalize          Output sorted/canonical CSS

Tip

The CLI supports stdin/stdout piping for CI integration: cat input.css | tailwindcss build -i - -o -. The canonicalize command is useful for diffing CSS output across versions — it produces a deterministic sort order.

PostCSS Plugin

// postcss.config.js
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {
      // Options (all optional):
      base: "./src",        // Base directory for file resolution
      optimize: {
        minify: true        // Enable CSS minification
      }
    }
  }
};

The PostCSS plugin maintains an LRU cache of compiled CSS roots. It performs incremental rebuilds when source files change and full rebuilds when the CSS input itself changes. AST conversion between PostCSS nodes and Tailwind's internal AST happens bidirectionally.

Vite Plugin

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";

export default {
  plugins: [
    tailwindcss({
      // Options (all optional):
      optimize: {
        minify: true        // Enable CSS minification (defaults to mode-based)
      }
    })
  ]
};

Two-step architecture:

1. Scan step (enforce: "pre") — intercepts CSS imports, registers them for processing, injects module graph tracking.
2. Generate step (no enforce) — compiles CSS with extracted candidates, handles HMR updates.

The plugin supports the Vite Environment API (Vite 7+) for SSR-aware builds. CSS changes trigger HMR updates; template changes that introduce new candidates trigger a full page reload.

Webpack Loader

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "@tailwindcss/webpack",
            options: {
              base: "./src",       // Base directory
              optimize: {
                minify: true       // Enable minification
              }
            }
          }
        ]
      }
    ]
  }
};

The Webpack loader uses an LRU cache (max 50 entries) with mtime-based invalidation. It performs a quick bail check on CSS files — if the content contains none of @import, @reference, @theme, @variant, @config, @plugin, @apply, or @tailwind, it skips processing entirely. CSS Modules are supported; when detected, the @property polyfill is disabled to avoid conflicts.

4. Deployment & Scaling

4.1 Integration Patterns

4.2 CI/CD Build Optimization

Caching strategy:

The oxide scanner and CSS compiler are deterministic — same inputs always produce the same outputs. Cache the following:

1. Node modules — node_modules/.pnpm/ (or equivalent for your package manager)
2. Turbo cache — .turbo/ if building from source
3. Standalone binary — download once per version, cache across builds

Build performance tips:

• The Rust oxide scanner is the fastest path. Avoid falling back to JS-based scanning.
• Use @source directives to limit the scanning scope. The auto-detection scans everything not in .gitignore, which can be expensive in large monorepos.
• The @source not directive prunes entire directory trees from scanning.
• For Docker builds, use multi-stage builds and copy only source files needed for CSS compilation.

4.3 Docker Considerations

# Multi-stage build example
FROM node:20-slim AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm tailwindcss build -i src/input.css -o dist/output.css --minify

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

Warning

Docker bind mounts can cause issues with the CLI's file watcher (@parcel/watcher). The native filesystem events may not propagate correctly through bind mounts on some host OS/Docker runtime combinations. See GitHub issue #18540. Use polling mode or volume mounts as a workaround.

4.4 Source Detection and Auto-Content

The oxide scanner performs automatic source detection:

1. Starts from the CSS file's directory (or project root).
2. Walks the directory tree, respecting .gitignore patterns.
3. Skips binary file extensions, node_modules, .git, and other known non-source directories.
4. Applies language-specific pre-processors to extract class candidates from templates.

Pre-processors by file type:

Ignore patterns (built-in):

The scanner automatically ignores files with these extensions: .avif, .bmp, .csv, .gif, .ico, .jar, .jpeg, .jpg, .lock, .map, .mp3, .mp4, .ogg, .otf, .pdf, .png, .svg, .ttf, .wav, .webm, .webp, .woff, .woff2, .zip (and others). Directories like node_modules, .git, .svn, .hg are also skipped.

5. Operations

5.1 Build Modes

Full build — Processes all CSS from scratch. Occurs on first build or when the CSS input file changes structurally (new @theme, @plugin, @import directives).

Incremental build — Only reprocesses changed candidates. Occurs when source files (templates, components) change but the CSS configuration remains the same. The PostCSS plugin, Vite plugin, and Webpack loader all support incremental builds.

Watch mode — Available via CLI (--watch) and implicitly in Vite/Webpack dev servers. Uses @parcel/watcher for native filesystem events. Triggers incremental or full rebuilds as appropriate.

5.2 Diagnostic Output and Debugging

Set the DEBUG environment variable to enable verbose logging from @tailwindcss-node:

DEBUG=1 tailwindcss build -i input.css -o output.css

Common error messages and their causes:

5.3 Migration from v3 to v4

The @tailwindcss/upgrade package provides an automated migration tool:

npx @tailwindcss/upgrade

What it migrates:

The upgrade tool uses tree-sitter and tree-sitter-typescript for robust template parsing — it does not rely on regex for JavaScript/TypeScript source transformations.

5.4 Monitoring Build Health

Key metrics to track in production build pipelines:

• Build time — Full builds should take <2s for typical projects. >5s indicates excessive source scanning scope.
• Output size — Minified CSS should be proportional to utility usage. Sudden size jumps indicate possible @apply proliferation or theme bloat.
• Candidate count — Monitor how many unique candidates the scanner extracts. False positives (strings that look like classes but aren't) increase compile time without affecting output.
• Source map validity — SOURCEMAP_BROKEN warnings (see issue #19930) can appear in Nuxt/Vite setups due to source map chain breaks.

6. Performance

6.1 Oxide Scanner Architecture

The Rust oxide engine is the performance-critical path. It uses a hierarchy of state machines to extract candidate class strings from arbitrary source files:

Input bytes
    │
    ├─► Language pre-processor (optional)
    │
    ├─► Fast skip (SIMD whitespace detection)
    │
    └─► State machine cascade:
        ├── CandidateMachine (top-level dispatcher)
        │   ├── UtilityMachine (e.g., "bg-blue-500")
        │   ├── VariantMachine (e.g., "hover:")
        │   ├── NamedUtilityMachine (e.g., "text-lg")
        │   ├── NamedVariantMachine (e.g., "group-hover:")
        │   ├── ArbitraryPropertyMachine (e.g., "[color:red]")
        │   ├── ArbitraryValueMachine (e.g., "bg-[#f00]")
        │   ├── ArbitraryVariableMachine (e.g., "bg-(--my-var)")
        │   ├── CssVariableMachine (e.g., "--tw-bg-opacity")
        │   ├── ModifierMachine (e.g., "/50")
        │   └── StringMachine (quoted strings)
        │
        └─► Extracted candidates (deduplicated)

Key optimizations:

1. SIMD fast-skip — Uses SIMD instructions to skip over large whitespace regions without entering state machines.
2. Byte classification macros — The classification-macros crate provides #[bytes(...)] and #[bytes_range(...)] proc macros that generate lookup tables for O(1) byte classification.
3. Rayon parallelism — File scanning is parallelized across CPU cores via rayon's work-stealing thread pool.
4. Glob hoisting — The scanner optimizes glob patterns by hoisting common prefixes, reducing directory traversal.
5. Language pre-processors — Strip non-relevant syntax before candidate extraction, reducing false positives and improving throughput.

6.2 N-API Bridge

The @tailwindcss-oxide package exposes the Rust scanner to Node.js via napi-rs:

class Scanner {
  constructor(options: {
    sources: Array<{ base: string; pattern?: string }>;
    globs?: Array<{ origin?: string; base: string; pattern: string }>;
  })

  scan(): string[]                    // Scan all sources, return candidates
  scan_files(files: string[]): string[] // Scan specific files
  files(): string[]                    // List discovered source files
  globs(): Array<{ base: string; pattern: string }>  // Active glob patterns
  normalized_sources(): Array<{ base: string; pattern: string }>
}

The N-API bridge in crates/node handles type conversion between Rust and JavaScript. Scanned results are deduplicated in Rust before crossing the N-API boundary to minimize serialization overhead.

6.3 CSS Compiler Performance

The TypeScript compiler processes candidates through several stages:

1. Candidate parsing — Each candidate string is parsed into a structured Candidate type (static, functional, or arbitrary).
2. Utility resolution — Candidates are matched against registered utilities. Theme values are resolved lazily.
3. Variant application — Variants are applied as wrappers around the resolved utility CSS.
4. AST construction — CSS AST nodes are created and deduplicated.
5. @apply expansion — Inline utility references are expanded recursively.
6. Serialization — The AST is serialized to a CSS string.

Incremental compilation reuses the design system state and only processes new candidates. The LRU caches in PostCSS (unbounded) and Webpack (max 50) store compiled results keyed by input CSS content hash.

6.4 lightningcss Optimization

The @tailwindcss-node package applies lightningcss for:

• Minification — Whitespace removal, shorthand collapsing, value optimization.
• Vendor prefixing — Based on browserslist targets.
• Modern CSS transforms — Lowers newer CSS features for older browsers.
• Nesting flattening — Resolves CSS nesting for browsers that don't support it.
• @property polyfill — Generates @property rules for registered custom properties (disabled in CSS Modules mode).

6.5 Performance Bottlenecks

Common bottlenecks in order of impact:

1. Source scanning scope — Scanning too many files is the #1 performance issue. Use @source to limit scope.
2. @apply chains — Each @apply triggers a mini-compilation. Deep chains compound.
3. Plugin count — Each plugin runs synchronously during compilation.
4. Import resolution — Deep @import chains require filesystem I/O for each resolution.
5. Source map generation — Adds ~10-20% overhead. Disable in production if not needed.

7. Security

7.1 Supply Chain Security

Published packages:

• All packages are published to npm under the @tailwindcss scope (owned by Tailwind Labs).
• Platform-specific oxide binaries are published as separate packages with optionalDependencies — npm/pnpm downloads only the binary for the current platform.
• The standalone binary is self-contained; no runtime dependency resolution occurs.

Native binary provenance:

The oxide binaries are compiled in CI from the crates/ source. The napi-rs build system cross-compiles for all 12 targets. The binary integrity is verified by npm's content-addressable storage (integrity hashes in lockfiles).

Caution

When using the standalone binary outside of npm (e.g., downloaded directly from GitHub releases), verify the binary hash against the published checksums. The standalone binary bundles @tailwindcss/forms, @tailwindcss/typography, and @tailwindcss/aspect-ratio — ensure these are versions you trust.

7.2 Configuration Injection Vectors

Warning

The @plugin and @config directives execute arbitrary JavaScript with the same permissions as the Node.js process. In CI environments, treat CSS files as code — a malicious @plugin "./exfil.js" directive in a CSS file could exfiltrate secrets. Apply the same review rigor to CSS files as you would to package.json scripts.

7.3 CSS Injection Considerations

Tailwind's utility-class approach reduces traditional CSS injection risks because:

1. No runtime CSS generation — CSS is compiled at build time, not at request time.
2. Deterministic output — Same input always produces same output; no user input influences CSS at runtime.
3. Arbitrary value sanitization — The compiler validates arbitrary values (e.g., bg-[url('...')]) during parsing.

However, the browser build (@tailwindcss/browser) compiles CSS at runtime in the client. In this mode:

• Class attributes from the DOM are used as compiler input.
• A malicious DOM mutation could inject unexpected CSS.
• The browser build should only be used for trusted content (prototyping, documentation, playgrounds).

Important

Never use @tailwindcss/browser in production applications where untrusted content can modify DOM class attributes. The MutationObserver-based scanning means any DOM change triggers recompilation with the new class values.

7.4 Content Security Policy (CSP)

The browser build injects <style> elements dynamically, requiring style-src 'unsafe-inline' or a nonce-based CSP. For build-time compilation (CLI, Vite, PostCSS, Webpack), no special CSP headers are needed — the output is a static CSS file.

7.5 Dependency Audit Surface

Core runtime dependencies (minimal attack surface):

The core tailwindcss package has zero runtime npm dependencies. All dependencies come from the integration packages (@tailwindcss-node, @tailwindcss-cli, etc.).

8. Developer Internals

8.1 Core Compiler (packages/tailwindcss)

The core package (55 files, ~1.1M characters) is the heart of the framework. It exports three primary entry points:

// Main compilation entry
function compile(
  css: string,
  options?: { base?: string; from?: string }
): Promise<{
  globs: Glob[];
  build(candidates: string[]): string;
  buildWithMaps(candidates: string[]): { css: string; map: SourceMap };
}>

// AST-level compilation
function compileAst(
  ast: AstNode[],
  options?: { base?: string; from?: string }
): Promise<{
  globs: Glob[];
  build(candidates: string[]): string;
}>

// Design system introspection (IntelliSense, tooling)
function __unstable__loadDesignSystem(
  css: string,
  options?: { base?: string }
): Promise<DesignSystem>

Note

The __unstable__loadDesignSystem export is used by the Tailwind CSS IntelliSense VS Code extension and other tooling. Despite the __unstable__ prefix, it is actively maintained and versioned alongside the compiler. It provides the full design system state including all registered utilities, variants, and theme values.

8.2 Key Internal Types

DesignSystem

The central object that holds all compiler state:

interface DesignSystem {
  theme: Theme
  utilities: Map<string, UtilityDefinition>
  variants: Map<string, VariantDefinition>
  // Internal compiler state
  features: Features
  polyfills: Polyfills
}

Theme

The theme is a CSS custom property store with namespace awareness:

class Theme {
  // Resolve a theme value by its full path
  resolve(path: string): string | undefined

  // Resolve with namespace awareness (e.g., "--color-" namespace)
  resolveNamespaced(namespace: string, key: string): string | undefined

  // Check if a namespace has any values
  hasNamespace(namespace: string): boolean
}

AstNode

The CSS AST is a union type:

type AstNode =
  | { kind: "rule"; selector: string; nodes: AstNode[] }
  | { kind: "at-rule"; name: string; params: string; nodes: AstNode[] }
  | { kind: "declaration"; property: string; value: string; important: boolean }
  | { kind: "comment"; value: string }
  | { kind: "context"; context: Record<string, string>; nodes: AstNode[] }
  | { kind: "at-root"; nodes: AstNode[] }

Features (Bitflags)

enum Features {
  None = 0,
  AtApply = 1 << 0,        // @apply directives present
  JsPluginCompat = 1 << 1, // JS plugin compatibility mode
  ThemeFunction = 1 << 2,  // --theme() function used
  Utilities = 1 << 3       // Utility generation needed
}

Polyfills (Bitflags)

enum Polyfills {
  All = ~0,
  AtProperty = 1 << 0  // @property rule generation
}

Candidate

Parsed utility class representation:

type Candidate =
  | { kind: "static"; value: string; variants: Variant[]; important: boolean }
  | { kind: "functional"; value: string; modifier?: string; variants: Variant[]; important: boolean }
  | { kind: "arbitrary"; property: string; value: string; variants: Variant[]; important: boolean }

Variant

type Variant =
  | { kind: "static"; value: string }
  | { kind: "functional"; value: string; modifier?: string }
  | { kind: "compound"; value: string; inner: Variant }
  | { kind: "arbitrary"; selector: string }

8.3 CSS Parser (css-parser.ts)

The custom CSS parser handles Tailwind-specific extensions while maintaining CSS spec compliance. It produces AstNode[] from raw CSS strings.

Key behaviors:

• Handles @theme, @plugin, @config, @source, @variant, @utility, @apply, @reference as first-class at-rules.
• Preserves comments in the AST for source map fidelity.
• Reports structured errors with line/column information (e.g., Missing opening { at css-parser.ts:427).
• Supports CSS nesting syntax natively.

8.4 Utility Registration and Resolution

Utilities are registered via the design system, either from the built-in set or via plugins:

// Static utility (fixed CSS output)
designSystem.utilities.set("sr-only", {
  // CSS declarations
});

// Functional utility (value-parameterized)
designSystem.utilities.set("bg-*", {
  // Resolve value from theme or arbitrary, generate CSS
});

The resolution process:

1. Parse candidate string into Candidate structure.
2. Look up utility by name in the registry.
3. For functional utilities, resolve the value against the theme namespace.
4. Apply any modifier (e.g., /50 for opacity).
5. Wrap in variant selectors (applied outside-in).
6. Return CSS AST nodes.

8.5 Variant System

Variants transform utility selectors. They are composable (stackable) and ordered by specificity:

Built-in variant categories:

• Pseudo-class: hover, focus, active, visited, first-child, last-child, etc.
• Pseudo-element: before, after, placeholder, file, marker, selection, etc.
• Responsive: sm, md, lg, xl, 2xl (from --breakpoint-* theme)
• Dark mode: dark (configurable: media query or class-based)
• Container queries: @sm, @md, @lg, etc.
• State: open, closed, disabled, enabled, checked, indeterminate, etc.
• Group/peer: group-hover, peer-focus, etc.
• Arbitrary: [&:nth-child(3)], [@media(hover:hover)], etc.

Circular dependency detection (index.ts:639) prevents infinite loops in custom variant definitions.

8.6 @apply Implementation (apply.ts)

The @apply directive is one of the most complex features. It works by:

1. Collecting all @apply directives in the AST.
2. For each directive, parsing the referenced utility classes.
3. Compiling each utility against the design system.
4. Inlining the resulting declarations at the @apply site.
5. Handling !important propagation.
6. Detecting and reporting circular @apply chains.

Restrictions:

• Cannot be used inside @keyframes blocks (apply.ts:36).
• Cannot reference unknown utilities (apply.ts:242).
• Recursive @apply is supported but circular references are detected and rejected.

8.7 @import Resolution

The compiler resolves @import directives using a chain of resolvers provided by @tailwindcss-node:

1. CSS resolver — Resolves bare specifiers against node_modules with CSS-specific extensions (.css).
2. ESM resolver — Resolves with ESM conditions (import, module).
3. CJS resolver — Fallback to CommonJS resolution (require, main).

All resolvers are built on enhanced-resolve with appropriate configuration. Resolution respects NODE_PATH environment variable for additional search paths.

URL rewriting ensures that relative URLs in imported CSS files are adjusted relative to the output file, not the source file.

8.8 Module Reference

packages/tailwindcss — Core Compiler

packages/@tailwindcss-node — Node.js Integration

packages/@tailwindcss-cli — CLI Tool

packages/@tailwindcss-postcss — PostCSS Plugin

packages/@tailwindcss-vite — Vite Plugin

packages/@tailwindcss-webpack — Webpack Loader

packages/@tailwindcss-browser — Browser Build

packages/@tailwindcss-oxide — N-API Bindings

packages/@tailwindcss-upgrade — Migration Tool

crates/oxide — Rust Extraction Engine

crates/node — N-API Bridge

crates/ignore — Gitignore Matching

crates/classification-macros — Proc Macros

8.9 Compilation Pipeline Detail

The full compilation pipeline from CSS input to CSS output:

1. CSS Input String
   │
2. ├─► CSS Parser (css-parser.ts)
   │   └─► AstNode[]
   │
3. ├─► @import Resolution (@tailwindcss-node/compile.ts)
   │   └─► Recursive: resolve path → read file → parse → inline AST
   │
4. ├─► Design System Initialization (index.ts)
   │   ├─► Process @theme → populate Theme
   │   ├─► Process @plugin → load JS, register utilities/variants
   │   ├─► Process @config → load JS config, merge
   │   ├─► Process @variant → register custom variants
   │   ├─► Process @utility → register custom utilities
   │   ├─► Process @source → configure oxide Scanner globs
   │   └─► Register built-in utilities + variants
   │
5. ├─► Oxide Scan (via Scanner.scan())
   │   └─► candidate strings[]
   │
6. ├─► build(candidates) called
   │   ├─► Parse candidates → Candidate[]
   │   ├─► Resolve each Candidate against DesignSystem
   │   ├─► Apply variants (outside-in wrapping)
   │   ├─► Expand @apply directives
   │   └─► Produce final AstNode[]
   │
7. ├─► Serialize AST → CSS string
   │
8. ├─► Source map generation (optional)
   │
9. └─► lightningcss optimization (optional, via @tailwindcss-node)
        ├─► Minification
        ├─► Vendor prefixing
        ├─► @property polyfill
        └─► Final CSS output

8.10 Code Patterns and Conventions

State machine pattern (Rust oxide):

Every scanner machine implements a common interface: accept a byte cursor, advance through states, and return either a matched span or a rejection. Machines are composable — CandidateMachine dispatches to child machines based on the first few bytes. This avoids backtracking and keeps extraction O(n) in file size.

Bitflag feature detection (TypeScript):

The Features and Polyfills enums use bitwise operations for zero-cost feature detection during compilation. The compiler checks features & Features.AtApply to decide whether to run the @apply expansion pass, avoiding unnecessary work.

LRU caching (PostCSS, Webpack):

Both the PostCSS plugin and Webpack loader use LRU caches to avoid recompilation. The PostCSS cache uses @alloc/quick-lru (unbounded by default). The Webpack loader caps at 50 entries. Cache keys are derived from CSS content hashes plus file modification times.

Atomic incremental builds:

The build() function returned by compile() is designed to be called repeatedly with growing candidate sets. Internally, it tracks which candidates have already been compiled and only processes new ones. This is the foundation of incremental rebuilds in all integrations.

Module resolution cascade:

The triple-resolver pattern in @tailwindcss-node/compile.ts (CSS → ESM → CJS) ensures compatibility with the full npm ecosystem. CSS files use style and css conditions; ESM uses import and module; CJS uses require and main. This handles edge cases like packages that only export CJS or use non-standard fields.

9. Integration Points

9.1 Plugin API

Tailwind CSS v4 supports JavaScript/TypeScript plugins loaded via @plugin:

@plugin "./my-plugin.ts";

// my-plugin.ts
import plugin from "tailwindcss/plugin";

export default plugin(function ({ addUtilities, addVariant, matchUtilities, theme }) {
  addUtilities({
    ".content-auto": { "content-visibility": "auto" },
  });

  matchUtilities(
    { "tab": (value) => ({ "tab-size": value }) },
    { values: theme("tabSize") }
  );

  addVariant("hocus", "&:hover, &:focus");
});

Tip

Plugins loaded via @plugin are resolved relative to the CSS file, not the project root. Use @config if you need to load a full v3-style configuration object with plugin arrays.

9.2 IntelliSense Integration

The __unstable__loadDesignSystem() export provides everything the Tailwind CSS IntelliSense VS Code extension needs:

• Complete list of registered utilities with their CSS output.
• Complete list of registered variants with their selector transformations.
• Full theme value map for autocomplete suggestions.
• Candidate validation for diagnostics.

9.3 PostCSS Ecosystem

The @tailwindcss/postcss plugin operates as a standard PostCSS plugin and can be composed with other PostCSS plugins:

module.exports = {
  plugins: {
    "postcss-import": {},         // Runs before Tailwind
    "@tailwindcss/postcss": {},   // Tailwind compilation
    "autoprefixer": {}            // Runs after (usually redundant — lightningcss handles this)
  }
};

Important

Unlike v3, Tailwind CSS v4's PostCSS plugin handles @import resolution internally. Using postcss-import alongside @tailwindcss/postcss can cause double-resolution issues. Remove postcss-import unless you have non-Tailwind CSS files that need it.

9.4 Build Tool Integration Matrix

9.5 Testing Strategy

The project uses vitest for unit and integration tests and Playwright for browser E2E tests.

Test organization:

packages/tailwindcss/
  __tests__/         Core compiler tests
integrations/
  cli/               CLI integration tests
  postcss/           PostCSS plugin tests
  vite/              Vite plugin tests
  webpack/           Webpack loader tests
  upgrade/           Migration tool tests

Running tests:

# Unit tests (vitest)
pnpm test

# Specific package
pnpm --filter tailwindcss test

# Integration tests
pnpm --filter @tailwindcss/integrations test

# Rust tests
cargo test --workspace

Test patterns:

• Compiler tests assert CSS output for given input CSS + candidate lists.
• Integration tests spin up real build tool processes and verify output files.
• Oxide tests verify candidate extraction against known inputs.
• Upgrade tests verify codemod transformations against before/after fixtures.

9.6 Build System

TypeScript packages are built with tsup (esbuild-based bundler):

pnpm build          # Build all packages via turbo
pnpm --filter tailwindcss build  # Build specific package

Rust crates are built with Cargo:

cargo build --release --workspace    # Build all crates
cargo build -p oxide --release       # Build oxide only

N-API binaries are built via napi-rs:

cd packages/@tailwindcss-oxide
pnpm build           # Builds native binary for current platform

Turborepo manages the build graph:

• turbo.json defines task dependencies (e.g., build depends on upstream build).
• Turbo caches build outputs — rebuilds only what changed.
• Remote caching can be enabled for CI.

Standalone binary:

cd packages/@tailwindcss-standalone
bun build ./src/index.ts --compile --target=bun-linux-x64 --outfile=tailwindcss

9.7 Contributing Workflow

# Clone and setup
git clone https://github.com/tailwindlabs/tailwindcss.git
cd tailwindcss
pnpm install
cargo build --workspace

# Development
pnpm dev              # Watch mode for all packages
pnpm test             # Run tests
pnpm format           # Prettier formatting

# Before submitting
pnpm build            # Full build
pnpm test             # Full test suite
cargo test            # Rust tests
cargo clippy          # Rust linting

9.8 Known Issues

9.9 Version Compatibility

Note

Vite 7 support was added in v4.2.x via the Vite Environment API. The plugin detects the Vite version at runtime and uses the appropriate API surface.

9.10 Upgrade Path: v3 to v4

The architectural changes from v3 to v4 are substantial:

The @tailwindcss/upgrade tool automates most of this migration. Run it in the project root and review the changes:

npx @tailwindcss/upgrade
git diff  # Review all changes before committing

Tip

The upgrade tool is conservative — it preserves functionality over style. After running it, manually review the generated @theme block for opportunities to simplify (e.g., removing values that match the default theme).