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 / developer-tools

Developer tools

Developer tools give engineers two command-line paths around Tailwind CSS. The build tool turns a CSS entry point and project source files into generated CSS. The upgrade tool moves an older project to the current CSS-based model while keeping its design choices and warning when it cannot make a safe change.

Tooling model

The command-line tools share the same view of a Tailwind project. CSS defines the design system, source files provide the class names that the project uses, and the compiler produces CSS for those classes. The build path repeats this work during development. The upgrade path changes the project inputs so later builds use the current model.

This diagram shows how the two command-line paths use shared compiler services for different user goals.

flowchart LR
    A[Project CSS and source files] --> B[Shared compiler services]
    B --> C[Generated CSS]
    B --> D[Project design information]
    D --> E[Upgrade transformations]
    E --> F[Current CSS, config, and source files]
    F --> B
    C --> G[File or standard output]

CSS build tooling

The CLI build tool is the direct command-line entry point for compiling a Tailwind project. It reads CSS from a file or standard input, finds class candidates in the configured project sources, and writes generated CSS to a file or standard output. A candidate is a class-like token that can select a Tailwind utility.

The build command supports both one-time and development use:

  • One-time builds produce CSS for a deploy or another build step.
  • Watch mode observes source files and CSS or configuration inputs, then rebuilds when they can change the result. Filesystem events are the default. Polling is available when event watching is not suitable, and --watch=always keeps the process running after standard input closes.
  • Optimization, minification, and source maps prepare output for different delivery needs.

Watch mode uses incremental work for source changes and a full compiler refresh when CSS or a loaded configuration or plugin module changes. This keeps normal edits fast while allowing design-system changes to affect the next build. If the platform watcher cannot load, polling provides a separate watch path instead of blocking one-time builds.

See CLI build workflow for the build stages and watch behavior.

References: packages/…/index.ts• L13-25 packages/…/index.ts• L31-80 packages/…/index.ts• L330-438 packages/…/index.ts• L522-693

Project upgrade tooling

The upgrade tool is a guided migration path for projects that use an older Tailwind model. It discovers the project's Tailwind stylesheets, links them to their configuration and imports, updates CSS and source files, and aligns package setup with the current release. The @tailwindcss/upgrade package exposes this migration as a runnable command from its built distribution.

The tool aims to preserve behavior rather than rewrite every file without review. It changes known CSS directives, theme and variant settings, compatible configuration values, and class names. It leaves complex configuration in place when it cannot convert it safely. It also reports files that it skips or changes so the engineer can inspect the result.

Template migration uses a safety boundary before it changes a class-like token. The check rejects tokens found in style blocks or inline style values, and it rejects values that belong to conditions, function calls, event expressions, variant properties, image placeholders, or emitted event names. It permits class positions such as class, className, conditional class expressions, and class maps. This prevents a design-token rename from changing unrelated application data.

The safety check also recognizes valid candidates from the current design system and accepts clear utility shapes such as variants, arbitrary properties, and value-bearing utilities. For ambiguous tokens, it requires string context and rejects nearby operators or expressions. Tests cover framework attributes, JavaScript and TypeScript expressions, component variant values, and class maps so migration changes remain limited to class positions.

The tool normally requires a clean Git work tree before it edits files. The --force option allows a migration to proceed when the work tree is not clean. After the migration, the project owner must verify the changes before committing them. See Upgrade tool transformations for the transformation groups and their limits.

References: packages/…/package.json• L13-23 packages/…/index.ts• L28-43 packages/…/index.ts• L44-89 packages/…/index.ts• L91-182 packages/…/index.ts• L261-289 packages/…/is-safe-migration.ts• L26-210 packages/…/is-safe-migration.ts• L213-322 packages/…/is-safe-migration.test.ts• L155-232

Shared compilation services

The CLI and upgrade tool use shared Node services to load CSS and JavaScript inputs in the context of the project. These services resolve imports, expose the Tailwind design system, and report dependencies that can affect the result. This shared boundary keeps command-line output aligned with other build-tool integrations.

Node API and compilation explains the shared service for tools that need direct program access. The regular CLI is the user-facing command. The Node API is the extension point for a host that needs to manage the build lifecycle itself.

References: packages/…/index.ts• L5-10 packages/…/compile.ts• L22-31 packages/…/compile.ts• L94-115 packages/…/compile.ts• L118-175

Command-line delivery

The command-line experience is available through a package-managed Node command and through standalone platform binaries. Both paths expose the same project-facing build behavior. The difference is how the runtime and native dependencies reach the machine.

Package-managed CLI

The package-managed CLI is the normal choice for a JavaScript project. The @tailwindcss/cli package exposes the tailwindcss command from its built distribution, and a package manager supplies the CLI and its dependencies. The command then uses the project's CSS entry point, source rules, configuration, and plugins to produce CSS.

The CLI can also canonicalize class groups for tools that need stable class order or current candidate spelling. That command reads candidate groups from arguments or standard input and returns text, JSON, or JSON Lines results. It loads the design system from a chosen CSS entry file, or from the default Tailwind import when no file is given. Each group is split into candidates, equivalent candidates are collapsed, logical properties are mapped to physical properties, and the result is sorted according to the design system.

Canonicalization supports both batch and streaming use. In streaming mode, each input line produces one output line, while JSON mode returns one array and JSON Lines mode returns one result object per line. A result keeps the original input, the normalized output, and whether the group changed. Plugin messages are sent to standard error so machine-readable output stays clean.

References: packages/…/package.json• L18-26 packages/…/index.ts• L29-80 packages/…/index.ts• L34-64 packages/…/index.ts• L77-141 packages/…/index.ts• L144-195 packages/…/index.ts• L265-293 packages/…/canonicalize.test.ts• L160-194

Standalone CLI

The standalone CLI is a platform executable for users who do not want to install or invoke Node for a Tailwind build. It carries the CLI, built-in Tailwind CSS assets, JavaScript APIs used by supported plugins, and the native pieces needed by its target platform.

The executable keeps project files as its input. It can use project source files and supported plugins while resolving the built-in Tailwind assets from inside the binary. The standalone build excludes the executable itself from source scanning so the tool cannot create CSS from its own bundled content. See Standalone packaging for artifact targets and release checks.

References: packages/…/index.ts• L9-62 packages/…/index.ts• L64-98 packages/…/index.ts• L303-319 integrations/…/standalone.test.ts• L19-51

Project change boundaries

The tools treat CSS, configuration, source files, and package setup as related parts of one project contract. A build must see every input that can change generated CSS. An upgrade must change the inputs together so the migrated project still describes the same design system.

Build input boundary

The build input boundary includes the CSS entry point, imported stylesheets, loaded configuration or plugin modules, and source paths used for candidate discovery. A change to source content can add or remove generated utilities. A change to CSS or a loaded module can change the compiler itself and requires a fresh build view.

This boundary is why watch mode distinguishes a source update from a compiler-input update. Source updates use an incremental candidate scan. Changes to the input CSS or a tracked configuration or plugin dependency recreate the compiler. Filesystem-event watching and polling use the same rebuild decision.

References: packages/…/index.ts• L270-325 packages/…/index.ts• L330-438 packages/…/index.ts• L522-658 packages/…/index.ts• L800-821

Upgrade safety boundary

The upgrade safety boundary is the point where an automatic change could alter project behavior without enough information. The tool analyzes stylesheet import paths and configuration shape before it applies changes. It can stop or keep an old configuration when imports cross incompatible layers or configuration values are too dynamic to convert.

Template candidate checks add another safety boundary. A token that looks like a utility can also be a CSS property, a prop value, a function argument, or an event name. The migration changes it only when the surrounding text supports a class interpretation. Otherwise it leaves the token unchanged for review.

The result is a partially automated migration. The tool handles known patterns and makes its limits visible. Engineers must treat warnings and unchanged files as review points rather than as proof that the project is fully migrated.

References: packages/…/analyze.ts• L167-186 packages/…/analyze.ts• L297-302 packages/…/migrate-js-config.ts• L42-57 packages/…/migrate-js-config.ts• L392-467 packages/…/is-safe-migration.ts• L31-67 packages/…/is-safe-migration.ts• L158-210

Project file boundary

The upgrade tool changes only files that belong to the project inputs it can identify. It uses CSS import relationships and source rules to find relevant files. Git-ignored files are skipped during source migration so generated output, dependencies, and other excluded paths are not changed by accident.

Changes are written in a way that keeps the old file until the new file is ready. This reduces the chance that an interrupted migration leaves a truncated CSS, template, or configuration file.

References: packages/…/index.ts• L294-411 packages/…/write-file-safely.ts• L5-18 packages/…/write-file-safely.ts• L23-47

Change checklist

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

  • Changes to the CLI entry point or its flags must keep the package-managed and standalone command surfaces aligned.
  • Changes to compiler dependency reporting must preserve full rebuilds for imported CSS, configuration, plugins, and their transitive modules.
  • Changes to source detection must keep explicit source rules, automatic discovery, ignored paths, and watch registration consistent.
  • Changes to upgrade transformations must keep CSS, configuration, package dependencies, and source class names in one migration contract.
  • Changes to migration safety checks must keep unsupported dynamic configuration, ambiguous stylesheet import paths, and non-class template tokens visible to the user.
  • Changes to standalone asset resolution or bundled plugin APIs must keep the executable behavior compatible with the package-managed CLI.
  • Changes to the event watcher or polling watcher must keep their rebuild decisions, cleanup behavior, and standard-input lifetime rules aligned.
  • Changes to canonicalize output or plugin logging must keep standard output machine-readable and preserve text, JSON, and JSON Lines contracts.

Important failure modes

TriggerConsequenceGuard
The CSS entry point or an imported configuration module is not tracked as a build dependency.Watch mode keeps stale generated CSS after a design change.Report every CSS and JavaScript dependency and use a full rebuild when one changes.
A source root or explicit source path is wrong.The scanner misses class candidates and the output lacks the related utilities.Validate source paths and keep the CSS source rules aligned with the scanner inputs.
The platform file watcher cannot load.Event-based watch mode cannot start.Use --watch --poll to use polling, or use a supported platform for event watching.
A canonicalize plugin writes logs to standard output.Text, JSON, or JSON Lines results become unsafe for downstream tools to parse.Redirect plugin console output to standard error and keep result data on standard output.
A canonicalize stream consumer sends malformed format values or no candidate groups.The command returns an error instead of a usable result stream.Validate --format and provide candidate groups through arguments or standard input.
The upgrade tool runs against a version mismatch between the manifest and installed package.Transformations can target the wrong Tailwind model.Install the version requested by the project before running the upgrade.
A migration runs with uncommitted work and the result is not isolated.Existing work becomes hard to separate from automated changes.Use a clean Git work tree or pass --force only when the changes are safely backed up.
A dynamic configuration or ambiguous import tree is treated as fully convertible.Theme, layer, or plugin behavior can change without a clear error.Keep the configuration and stylesheet safety checks conservative and review warnings.
A class-like token in a style value, prop value, event expression, or function argument is treated as a class.The migration changes application behavior outside the Tailwind class contract.Require class context and leave ambiguous template tokens unchanged.
A standalone binary lacks the platform or native runtime support it needs.The command cannot start or cannot scan project files.Use the binary for the matching operating system, architecture, and libc target.

Key files

FileWhy to read it
packages/…/index.tsDefines the user-facing CLI commands and the top-level build and canonicalize surfaces.
packages/…/package.jsonDefines the published package command and distribution boundary for the package-managed CLI.
packages/…/index.tsShows the command-line build lifecycle, output choices, source scanning, and watch rebuild boundary.
packages/…/index.tsDefines candidate normalization, stream formats, design-system loading, and plugin log routing.
packages/…/canonicalize.test.tsShows the user-facing canonicalize contracts for batch input, streams, result formats, and plugin logs.
packages/…/index.tsShows the end-to-end migration flow from project checks through CSS, source, and dependency updates.
packages/…/package.jsonDefines the published upgrade command and its runtime package boundary.
packages/…/migrate.tsShows the high-level CSS transformation stages used during migration.
packages/…/migrate.tsShows how source class candidates are found, changed when safe, and written back.
packages/…/is-safe-migration.tsDefines the safety boundary that prevents class renames in non-class template values.
packages/…/is-safe-migration.test.tsShows the supported class contexts and the application values that migration must leave unchanged.
packages/…/migrate-js-config.tsShows which configuration values can move to CSS and when the old configuration must remain.
packages/…/compile.tsDefines the shared project loading and dependency boundary used by command-line compilation.
packages/…/index.tsShows how the standalone executable supplies embedded assets and APIs to the shared CLI.
packages/…/build.tsDefines the platform executable targets and checksum artifacts.