Getting started

This page is for working on the framework, not for using it in an application. For end-user setup see tailwindcss.com.

Prerequisites

From .github/CONTRIBUTING.md:

• Node.js (the repo uses @types/node@^22.19.17 from the pnpm catalog).
• pnpm — the package manager. The repo pins packageManager: pnpm@9.6.0 in package.json.
• Rustup. The toolchain version is locked in rust-toolchain.toml.

integrations/ tests run real pnpm/yarn/npm/bun builds, so you may want all four package managers installed if you plan to work on integration tests. The standalone CLI (packages/@tailwindcss-standalone) is built with Bun.

Install

# Install JS dependencies for every workspace package.
pnpm install

# Install Rust toolchain + WASM target used by some downstream consumers.
rustup default stable
rustup target add wasm32-wasip1-threads

Build

# Build every package except the playgrounds (tsup + cargo).
pnpm build

Behind the scenes this runs turbo build --filter=!./playgrounds/*. The postbuild step (scripts/pack-packages.mjs) creates tarballs in dist/ so the integration tests can install built artifacts from disk.

To build a single package:

pnpm --filter tailwindcss build
pnpm --filter @tailwindcss/cli build

The Rust crates build through cargo automatically as a turbo task because the @tailwindcss/oxide package's build.rs invokes cargo.

Run the build in watch mode

pnpm dev   # turbo dev across all packages (skips playgrounds)

Individual playgrounds:

pnpm vite      # packages/@tailwindcss-vite-driven sandbox at playgrounds/vite
pnpm nextjs    # the Next.js playground at playgrounds/nextjs

playgrounds/v3 is a Tailwind v3 sandbox used to verify the upgrade tool.

Test

Command	What it runs
pnpm test	cargo test plus vitest run --hideSkippedTests (TS unit tests)
pnpm tdd	Vitest in watch mode
pnpm test:integrations	Integration tests under integrations/ (rebuilt with pnpm build first)
pnpm test:ui	Playwright UI tests for tailwindcss and @tailwindcss/browser
pnpm bench	Vitest benchmarks (*.bench.ts)

For the Rust side specifically:

cargo test                              # all crates
cargo test -p tailwindcss-oxide         # just the scanner

Lint and format

pnpm lint    # prettier --check + turbo lint (which runs `tsc --noEmit` per package)
pnpm format  # prettier --write

Prettier configuration lives in the "prettier" section of package.json. Notable: semi: false, singleQuote: true, printWidth: 100. The TS checking is type-only (tsc --noEmit) — there is no JavaScript output target for the compiler package since tsup handles bundling.

Repository layout cheat sheet

.
├── packages/
│   ├── tailwindcss/          # Core compiler (TypeScript)
│   ├── @tailwindcss-cli/     # CLI binary
│   ├── @tailwindcss-vite/    # Vite plugin
│   ├── @tailwindcss-postcss/ # PostCSS plugin
│   ├── @tailwindcss-webpack/ # Webpack loader
│   ├── @tailwindcss-node/    # Node-only shared helpers
│   ├── @tailwindcss-browser/ # Browser bundle
│   ├── @tailwindcss-upgrade/ # v3 → v4 upgrade tool
│   ├── @tailwindcss-standalone/ # Bun-built native binary
│   └── internal-example-plugin/ # Test fixture for plugin loading
├── crates/
│   ├── oxide/                # Scanner + extractor (Rust)
│   ├── node/                 # NAPI binding → @tailwindcss/oxide
│   ├── ignore/               # Vendored ignore crate
│   └── classification-macros/ # Proc-macros for byte tables
├── integrations/             # End-to-end vitest suites per integration
├── playgrounds/              # Manual sandboxes (Vite, Next.js, v3)
├── patches/                  # pnpm patch files for @parcel/watcher and lightningcss
├── scripts/                  # Release + packaging scripts (.mjs)
├── package.json              # Root package + scripts
├── pnpm-workspace.yaml       # Workspace layout
├── turbo.json                # Turborepo task pipeline
├── Cargo.toml                # Rust workspace
├── rust-toolchain.toml       # Pinned Rust toolchain
└── vitest.config.ts          # Root Vitest config (browser/jsdom workspace projects)

What to read first

• package.json, pnpm-workspace.yaml, turbo.json — entry points to the build graph.
• packages/tailwindcss/src/index.ts — the compile/compileAst entry points.
• packages/@tailwindcss-cli/src/index.ts — concrete consumer of the compile/scan loop.
• crates/oxide/src/scanner/mod.rs — the scanner implementation.
• integrations/utils.ts — the harness used by integration tests; useful as a reference for "how do I drive a build?"

After this page, see How to contribute for the development workflow and Architecture for the high-level design.