Merlin/
tailwindlabs/tailwindcss
Public Wiki93,403View on GitHub
Agent API
Want tailwindlabs/tailwindcss knowledge in your AI?

React

Tailwind CSS v4 - a utility-first CSS framework that compiles atomic CSS classes into optimized stylesheets. This is the core framework monorepo containing the CSS compilation engine, a high-performance Rust-based class scanner (Oxide), build tool integrations (Vite, PostCSS, Webpack), CLI tools, and an automated v3-to-v4 migration system.

Tech Stack

ReactNext.jsTailwind CSSVue.jsExpress.jsTypeScriptVitest

Key Features

  • Core CSS Compilation Engine
  • Oxide Scanner (Rust)
  • Build Tool Integrations
  • v3 Compatibility Layer
  • Automated Upgrade Tool
  • Standalone Binary
  • Browser Compilation

Entry Points

Start here when working with this codebase

Core CSS Compilation
packages/tailwindcss/src/index.ts

Main entry point for Tailwind CSS compilation - exports compile function and core APIs

Start here when modifying core CSS generation, adding new at-rules, or changing compilation behavior

CLI Entry
packages/@tailwindcss-cli/src/index.ts

Command-line interface entry point - handles build, watch, and init commands

Start here when adding new CLI commands or modifying CLI behavior

Vite Plugin
packages/@tailwindcss-vite/src/index.ts

Vite integration plugin - handles HMR, CSS transformation, and build optimization

Start here when fixing Vite-specific issues or adding Vite integration features

PostCSS Plugin
packages/@tailwindcss-postcss/src/index.ts

PostCSS plugin integration - processes CSS through PostCSS pipeline

Start here when modifying PostCSS integration or fixing PostCSS-specific bugs

Upgrade Tool
packages/@tailwindcss-upgrade/src/index.ts

v3 to v4 migration tool entry - orchestrates codemods and file transformations

Start here when adding new migration codemods or fixing upgrade issues

Oxide Scanner (Rust)
crates/oxide/src/lib.rs

High-performance Rust scanner for extracting Tailwind classes from source files

Start here when optimizing class extraction or adding new language support

Node Bindings
crates/node/src/lib.rs

NAPI bindings exposing Rust oxide scanner to Node.js

Start here when adding new Rust functions to expose to JavaScript

Browser Package
packages/@tailwindcss-browser/src/index.ts

Browser-based Tailwind compilation for playgrounds and REPLs

Start here when modifying browser-specific compilation or playground features

How to Make Changes

Common modification patterns for this codebase

Add a new CSS utility class

1
packages/tailwindcss/src/utilities.ts

Add utility definition to the utilities map with CSS properties and values

Pattern: Follow the pattern of existing utilities like 'flex' or 'grid' - each utility maps a class name to CSS declarations

2
packages/tailwindcss/src/utilities.test.ts

Add test cases for the new utility covering all variants

Pattern: Follow test structure in this file - use css() helper to verify generated CSS output

3
packages/tailwindcss/src/index.ts

Verify utility is registered in the compilation pipeline (usually automatic)

Pattern: Check how utilities are loaded and registered in the compile function

Conventions to follow:

Utility names use kebab-case (e.g., 'flex-wrap')Support arbitrary value syntax with square bracketsInclude negative variants where applicable (e.g., '-m-4')Add responsive and state variants automatically via the candidate system

Add a new CSS at-rule (like @apply or @theme)

1
packages/tailwindcss/src/ast.ts

Define AST node type for the new at-rule if needed

Pattern: Follow AtRule interface pattern - see how @theme and @apply nodes are defined

2
packages/tailwindcss/src/index.ts

Add at-rule processing logic in the compile function's AST walk

Pattern: See how @theme is processed - walk the AST, identify the at-rule, transform it

3
packages/tailwindcss/src/index.test.ts

Add comprehensive tests for the new at-rule

Pattern: Follow existing at-rule tests - test parsing, transformation, and edge cases

Conventions to follow:

At-rules start with @ symbolProcess at-rules during AST walk phaseRemove or transform at-rules before final CSS outputSupport nesting within at-rules where appropriate

Add support for a new template language in Oxide scanner

1
crates/oxide/src/extractor/pre_processors/mod.rs

Register the new pre-processor module

Pattern: Follow how pug.rs and haml.rs are registered - add mod declaration and export

2
crates/oxide/src/extractor/pre_processors/

Create new pre-processor file (e.g., svelte.rs) implementing the PreProcessor trait

Pattern: Follow crates/oxide/src/extractor/pre_processors/pug.rs - implement pre_process() to extract class-relevant content

3
crates/oxide/src/lib.rs

Wire up the pre-processor to file extension detection

Pattern: See how file extensions map to pre-processors in the Scanner implementation

4
crates/oxide/tests/

Add integration tests for the new language

Pattern: Follow existing test patterns - create test fixtures and verify extracted candidates

Conventions to follow:

Pre-processors extract class-relevant strings from template syntaxUse state machines for parsing (see crates/oxide/src/extractor/machine.rs)Handle both static classes and dynamic class bindingsPreserve source positions for accurate error reporting

Add a new CLI command

1
packages/@tailwindcss-cli/src/commands/

Create new command file (e.g., lint.ts) with command implementation

Pattern: Follow packages/@tailwindcss-cli/src/commands/build.ts - export default async function with args parsing

2
packages/@tailwindcss-cli/src/index.ts

Register the new command in the CLI router

Pattern: See how 'build' and 'init' commands are registered - add case in command switch

3
packages/@tailwindcss-cli/src/help.ts

Add help text for the new command

Pattern: Follow existing help text format - include usage, options, and examples

Conventions to follow:

Commands are async functions accepting parsed argumentsUse consistent flag naming (--output, --watch, --minify)Exit with appropriate codes (0 success, 1 error)Support both short (-o) and long (--output) flag forms

Add a new upgrade codemod for v3 to v4 migration

1
packages/@tailwindcss-upgrade/src/codemods/css/

Create CSS codemod if transforming CSS files

Pattern: Follow packages/@tailwindcss-upgrade/src/codemods/css/migrate-at-apply.ts - export function that transforms AST

2
packages/@tailwindcss-upgrade/src/codemods/template/

Create template codemod if transforming HTML/JSX class attributes

Pattern: Follow packages/@tailwindcss-upgrade/src/codemods/template/migrate-legacy-classes.ts - use candidate parsing

3
packages/@tailwindcss-upgrade/src/codemods/config/

Create config codemod if transforming tailwind.config.js

Pattern: Follow existing config codemods - use jscodeshift for AST manipulation

4
packages/@tailwindcss-upgrade/src/index.ts

Register the codemod in the upgrade pipeline

Pattern: See how codemods are orchestrated - add to appropriate phase (css, template, or config)

Conventions to follow:

Codemods should be idempotent (safe to run multiple times)Preserve formatting and comments where possibleLog clear messages about what was changedHandle edge cases gracefully without crashing

Add integration tests for a build tool plugin

1
integrations/utils.ts

Review test utilities and helpers available

Pattern: This file provides test harness - use candidate(), css(), and exec() helpers

2
integrations/vite/

Add Vite integration test (or integrations/webpack/, integrations/postcss/)

Pattern: Follow existing integration test structure - create fixture, run build, assert output

3
vitest.config.ts

Verify test is included in test configuration

Pattern: Check include patterns cover your new test directory

Conventions to follow:

Integration tests use real build tool executionCreate minimal fixture projects for each test caseTest both development and production buildsVerify CSS output contains expected utilities

Expose new Rust function to Node.js

1
crates/oxide/src/lib.rs

Implement the core Rust function

Pattern: Follow existing public functions - use appropriate Rust types and error handling

2
crates/node/src/lib.rs

Add NAPI binding for the function using #[napi] macro

Pattern: Follow existing bindings like scan_files - use napi-rs types for JS interop

3
packages/@tailwindcss-node/src/index.ts

Export the new function from the Node package

Pattern: Import from native binding and re-export with TypeScript types

4
crates/node/build.rs

Verify build configuration if adding new dependencies

Pattern: Check NAPI build settings are correct for the new binding

Conventions to follow:

Use #[napi] macro for automatic binding generationConvert Rust errors to JavaScript exceptions properlyUse Buffer for binary data, String for textDocument function signatures with JSDoc in TypeScript

Add v3 config compatibility feature

1
packages/tailwindcss/src/compat/config.ts

Add config transformation logic for the v3 feature

Pattern: Follow existing config normalization - transform v3 config shape to v4 internal format

2
packages/tailwindcss/src/compat/plugin-api.ts

Update plugin API compatibility if needed

Pattern: See how v3 plugin functions are adapted to v4 internals

3
packages/tailwindcss/src/compat/apply-config-to-theme.ts

Handle theme merging for the feature

Pattern: Follow theme extension patterns - merge user config with defaults

Conventions to follow:

Compat layer transforms v3 config to v4 internal formatPreserve backward compatibility without breaking v4 featuresLog deprecation warnings for v3-only featuresTest with real v3 configs from popular projects

Coding Conventions

Standards and patterns used in this codebase

file-organization

Monorepo structure: apps/ contains deployable applications, packages/ contains shared libraries

Packages: packages/@tailwindcss-browser, packages/@tailwindcss-cli, packages/@tailwindcss-node
packages/@tailwindcss-browserpackages/@tailwindcss-cli
naming

File naming uses: kebab-case

vitest.config.ts, utils.ts, version-packages.mjs, build.rs, playwright.config.ts
vitest.config.tsintegrations/utils.tsscripts/version-packages.mjs
code-style

TypeScript is the primary language

All new files should be .ts or .tsx
vitest.config.tsintegrations/utils.tspackages/@tailwindcss-browser/playwright.config.ts
testing

Tests use .test. pattern

Test files are named like component.test.ts or placed in __tests__/
integrations/postcss/next.test.tsintegrations/postcss/source.test.tsintegrations/upgrade/index.test.ts
configuration

Configuration is centralized in config files

Config files: vitest.config.ts, packages/@tailwindcss-browser/playwright.config.ts
vitest.config.tspackages/@tailwindcss-browser/playwright.config.tspackages/@tailwindcss-browser/tsup.config.ts
module-exports

Use index.ts barrel files to export module public API

Each module has index.ts that re-exports public functions
packages/@tailwindcss-cli/src/index.tspackages/@tailwindcss-node/src/index.tspackages/@tailwindcss-browser/src/index.ts
typescript

Types are defined in dedicated type files

Type files: packages/@tailwindcss-standalone/src/types.d.ts
packages/@tailwindcss-standalone/src/types.d.ts