This document explains the build system for the Tailwind CSS v4 monorepo, covering the tools and processes used to compile TypeScript/JavaScript packages, native Rust modules, and multi-platform distribution artifacts. It details the build orchestration, cross-compilation strategy for the native engine, and the integration of tsup, cargo, and napi-rs.
For information about the release pipeline and npm publishing, see 6.4 Release Pipeline For local development setup and development scripts, see 6.1 Development Workflow
The Tailwind CSS build system employs a hybrid stack to handle both high-level JavaScript integrations and performance-critical native logic:
| Build Tool | Purpose | Used By |
|---|---|---|
tsup | TypeScript/JavaScript bundler (ESM/CJS) | tailwindcss, @tailwindcss/postcss, etc. |
cargo | Rust package manager and compiler | tailwindcss-oxide (core), tailwind-oxide (bindings) |
napi-rs | Rust → Node.js native bindings | tailwind-oxide (crates/node) |
turbo | Monorepo build orchestrator | Workspace-level task execution |
pnpm | Package manager & workspace manager | All packages |
Sources: packages/tailwindcss/tsup.config.ts1-3 crates/node/Cargo.toml11-17 turbo.json4-19
All TypeScript packages in the monorepo use tsup for compilation. The configuration targets both ESM and CJS formats while generating type definitions packages/tailwindcss/tsup.config.ts4-34 A key build-time feature is the injection of the FEATURES_ENV environment variable, which defaults to insiders unless specified, allowing for feature flagging during the build process packages/tailwindcss/tsup.config.ts15-17
Title: TypeScript Build Flow
Sources: packages/tailwindcss/tsup.config.ts3-34 turbo.json37-41
The native engine is split into two primary crates: tailwindcss-oxide (the core logic) and tailwind-oxide (the Node.js bindings) crates/oxide/Cargo.toml2 crates/node/Cargo.toml3 The core crate provides the high-performance Scanner and Extractor logic used for parsing utility candidates crates/oxide/src/lib.rs1-12
The bindings are generated using napi-rs and target Node-API version 4 for broad compatibility crates/node/Cargo.toml11 The build process for the native module is orchestrated by turbo, which tracks inputs across both the core Rust source and the Node.js wrapper turbo.json5-19
Title: Oxide Native Build Pipeline
Sources: crates/node/Cargo.toml9-17 crates/node/build.rs1-3 turbo.json5-19 crates/oxide/src/lib.rs1-12
Tailwind CSS v4 distributes native binaries for a wide variety of architectures. To ensure consistent builds, the project pins the Rust toolchain to version 1.95.0 rust-toolchain.toml1-4
The repository includes specialized Cargo configurations for cross-compilation, particularly for Linux and Windows targets:
aarch64 and armv7 crates/node/.cargo/config.toml1-7+crt-static) to ensure the binary runs on systems without the VC++ runtime installed crates/node/.cargo/config.toml9-12-Wl,-z,nodelete to prevent issues with shared library unloading crates/node/.cargo/config.toml13-14The build system includes complex logic for handling different file types during the scanning process. The tailwindcss-oxide crate implements language-specific pre-processors (e.g., for Ruby and Vue) to clean source files before candidate extraction crates/oxide/src/extractor/pre_processors/ruby.rs28-32 crates/oxide/src/extractor/pre_processors/vue.rs14-15
Furthermore, the build system optimizes glob patterns to minimize I/O during scanning. The hoist_static_glob_parts function attempts to move static directory segments into the base path to narrow the scope of file system walkers crates/oxide/src/glob.rs14-18
Title: Glob Optimization Data Flow
Sources: crates/oxide/src/glob.rs14-66 crates/oxide/src/glob.rs91-133 crates/oxide/src/glob.rs157-187
The turbo.json configuration defines strict input/output boundaries for the native build tasks. It caches the resulting .node binaries and generated TypeScript definitions based on hashes of the Rust source, Cargo manifests, and build scripts turbo.json5-19
The native engine relies on several high-performance Rust crates:
rayon: Used for parallelizing file scanning and candidate extraction crates/oxide/Cargo.toml10fxhash: Used for faster hashing in internal maps compared to the default SipHash crates/oxide/Cargo.toml11bstr: Used for efficient byte-level string manipulation, avoiding UTF-8 validation overhead where possible crates/oxide/Cargo.toml7Sources: turbo.json1-19 crates/oxide/Cargo.toml6-21 crates/node/Cargo.toml9-17