CLI build workflow
The CLI turns a Tailwind CSS entry file and project source files into generated CSS. It accepts files or standard streams, can keep the result current during development, and can run as a self-contained executable when a project does not use a local Node-based install. For the wider command-line tool view, see Developer tools. For transformations, see Upgrade tool transformations.
Command surface
The command line has two user-facing paths: the build path and the candidate canonicalization path. An omitted command means build, while build makes the same path explicit; canonicalize is a separate utility for normalizing class candidate groups from arguments or standard input.
Argument model
The CLI converts raw arguments into typed options before it starts a build. Long options have short aliases where useful, absent options receive a defined default, and the last value wins when an option is repeated. A single - remains available as the special stream value instead of being treated as a missing option value.
The main build options form these groups:
| Group | Options | Purpose |
|---|---|---|
| Sources and destination | --input/-i, --output/-o, --cwd | Select the CSS source, the CSS destination, and the base directory for relative paths. |
| Development rebuilds | --watch/-w, --poll | Keep the process active and choose file events or timed polling. |
| Output form | --minify, --optimize, --map | Compress or optimize CSS and emit an inline or separate source map. |
| Terminal behavior | --silent, --help/-h | Control status output or show usage information. |
The CLI shows help for an interactive invocation without a command and reports an invalid non-option command with a failure status. This keeps command mistakes separate from build errors.
References: packages/…/index.ts• L9-80 packages/…/args.ts• L3-25 packages/…/args.ts• L70-121
Candidate canonicalization
The canonicalization path turns each candidate group into a stable form for comparison or tooling. It can read groups from positional arguments or process them line by line from standard input, then returns plain text, JSON, or newline-delimited JSON with the normalized value and whether it changed.
The CSS entry defines the design system used for normalization. When a plugin writes to the console while it loads or compiles a candidate, the CLI redirects that diagnostic output to standard error so standard output remains machine-readable.
References: packages/…/index.ts• L13-19 packages/…/index.ts• L47-65 packages/…/index.ts• L103-140 packages/…/index.ts• L144-195 packages/…/index.ts• L282-293 packages/…/canonicalize.test.ts• L122-194
Build lifecycle
The build path establishes a project base, reads the CSS entry, discovers source files, compiles candidates into CSS, and sends the result to the selected destination. The same lifecycle supplies the first result before watch mode begins.
Input and output channels
The input channel is either a named CSS file, standard input, or an implicit entry that imports Tailwind CSS when no input is given. The output channel is either a named file or standard output; the default output is standard output. Relative paths use --cwd as their base, and the CLI rejects a missing input file or an input and output path that are the same.
The file writer creates missing parent directories and avoids rewriting a file when its contents are unchanged. This reduces needless downstream work and makes a watch process quiet when a rebuild produces the same CSS.
References: packages/…/index.ts• L132-195 packages/…/utils.ts• L4-34 integrations/…/index.test.ts• L101-241
CSS generation and output forms
The compiler combines the authored CSS entry with candidates found in the configured source set. Imported stylesheets, configuration files, and plugins extend that input and can affect the generated result. After compilation, the CLI can optimize the CSS, minify it, and attach source-map data either inside the CSS or in a separate map file.
The build reports errors on standard error and uses a non-zero process status for one-off failures. Normal progress and timing messages can be suppressed with --silent without changing the generated CSS.
This diagram shows how project inputs become the CSS artifact or stream returned by the CLI.
flowchart LR
A[CSS entry or stdin] --> B[Compiler]
C[Project source files] --> D[Candidate scan]
D --> B
B --> E[Generated CSS]
E --> F[Optional optimization and source map]
F --> G[Output file or stdout]
References: packages/…/index.ts• L202-267 packages/…/index.ts• L502-520 packages/…/compile.ts• L22-63 packages/…/optimize.ts• L29-55 packages/…/source-maps.ts• L6-59
Watch mode
Watch mode performs one normal build and then waits for changes in the source set and the files that can change the build definition. It batches nearby changes and chooses the least costly rebuild that can still produce a correct result.
Change detection
The default watcher uses file-system events. Polling is an alternative for systems where the native watcher is unavailable or unreliable; --poll without a number uses a 250 millisecond interval, while a numeric value sets the interval in milliseconds. Polling ignores the output and source-map files so that the CLI does not rebuild from its own writes. Event-based watching ignores the output file and batches other watched file events.
The watcher derives directories from the compiler’s normalized source entries. It removes nested duplicates and debounces events into one change batch. A closed standard input ends the watch process by default; --watch=always keeps the process alive after standard input closes.
References: packages/…/index.ts• L44-55 packages/…/index.ts• L330-341 packages/…/index.ts• L522-679 packages/…/index.ts• L682-797 packages/…/index.ts• L850-866
Rebuild strategy
The watcher treats a change in ordinary content as an incremental update. It scans only the changed files and adds any new candidates to the existing compiler state. A change in the CSS entry or in a configuration, plugin, or imported dependency requires a full rebuild because it can change the design system or the set of files being watched.
If an incremental scan finds no new candidates, the CLI leaves the output unchanged. A full rebuild recreates the compiler and watcher set, then scans the complete source set. A build error is shown without stopping the watch process, so fixing the changed file can restore the next build.
References: packages/…/index.ts• L346-438 packages/…/index.ts• L538-570 packages/…/index.ts• L604-663 packages/…/index.ts• L800-822
Dependency watching
Dependency watching extends source-file watching to files that define how the CSS is built. The compiler reports loaded CSS and JavaScript dependencies to the CLI, which keeps them in the full-rebuild set alongside the entry file.
Dependency set
CSS imports are direct build dependencies. A locally loaded configuration or plugin also brings its relative module dependencies into the set, including transitive files. This means a change to a theme file used by a configuration can trigger a full rebuild even when the main CSS entry did not change.
The dependency set is separate from candidate source files. Candidate files usually need only an incremental scan, while dependency files can alter compiler inputs and therefore require compiler recreation.
References: packages/…/compile.ts• L94-103 packages/…/compile.ts• L118-175 packages/…/get-module-dependencies.ts• L51-105 packages/…/index.ts• L270-301 packages/…/index.ts• L800-822
Dependency recovery
When a dependency is removed or becomes invalid, the current build can fail while the watcher remains active. The CLI restores the last known dependency set after the failure. When the file returns, that restored path can trigger another full rebuild and let the process recover without a restart.
References: packages/…/index.ts• L443-483 packages/…/index.ts• L620-635 integrations/…/index.test.ts• L1421-1499
Standalone executable
The standalone executable provides the same CLI workflow as the package-based command while bundling the runtime pieces needed to run on supported platforms. It still reads the project’s CSS, source files, configuration, and plugins from the working environment.
Self-contained runtime
The executable supplies the Tailwind CSS entry styles and the JavaScript APIs that project configurations and plugins may import. It also supports the first-party forms, typography, and aspect-ratio plugins used by a project. The CLI excludes its own executable from candidate scanning so placing the binary inside a project does not add accidental class candidates.
References: packages/…/index.ts• L1-18 packages/…/index.ts• L29-62 packages/…/index.ts• L64-98 packages/…/index.ts• L303-311 integrations/…/standalone.test.ts• L19-51 integrations/…/standalone.test.ts• L54-93
Platform delivery
The standalone package produces separate binaries for supported operating systems and CPU targets. Its build also records checksums for the produced artifacts. At use time, the selected binary runs the same input, output, watch, and dependency behavior described above.
References: packages/…/build.ts• L22-34 packages/…/build.ts• L38-74 packages/…/build.ts• L88-106 packages/…/package.json• L14-35
Change checklist
When these files or sections are changed, remember to consider these:
- Build option definitions, command routing, and help output must keep the same flag names, aliases, defaults, and stream sentinel rules.
- Input, output, and source-map path rules must stay aligned with file creation and unchanged-content checks.
- Compiler dependency reporting must stay aligned with full-rebuild classification and module cache invalidation.
- Source normalization changes must update both event-based directory watching and polling file selection.
- Canonicalization output formats must keep candidate results on standard output while plugin diagnostics stay on standard error.
- Standalone runtime resolution and platform targets must stay aligned with bundled CSS entrypoints, plugin APIs, native artifacts, and executable self-exclusion.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The input path does not exist | The one-off build exits before compilation. | Validate the input path before reading it. |
| The input and output paths are identical | The CLI refuses to overwrite its source. | Use distinct paths or use standard input/output. |
| Polling receives no value or a non-positive value | Watch mode exits with an option error. | Use --poll for the default interval or a positive millisecond value. |
| The native file watcher cannot load | Event-based watch mode cannot start. | Use polling with --watch --poll. |
| A watched dependency is deleted | The current rebuild reports an error, but the process stays alive. | Restore the dependency; the saved dependency set enables recovery. |
| Standard input closes during normal watch mode | The CLI stops and cleans up watchers. | Use --watch=always when the process must outlive standard input. |
| The standalone executable is scanned as project content | Its bundled text could create false candidates. | The build excludes the current executable from source scanning. |
| Plugin diagnostics are written to standard output | Text, JSON, or JSONL canonicalization output becomes unsafe for consumers. | Redirect plugin console output to standard error. |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | See command routing, build defaults, help behavior, and process-level exit handling. |
| packages/…/args.ts | See the shared contract for typed flags, aliases, defaults, and stream values. |
| packages/…/index.ts | See candidate-group input, output formats, design-system loading, and console stream separation. |
| packages/…/canonicalize.test.ts | See the machine-readable and streaming contract for candidate normalization. |
| packages/…/index.ts | Follow the complete build, output, watch, rebuild, and dependency-watch lifecycle. |
| packages/…/utils.ts | See standard-input collection and safe output-file writes. |
| packages/…/compile.ts | Understand the compiler-facing services that load CSS and JavaScript dependencies. |
| packages/…/get-module-dependencies.ts | Understand how relative configuration and plugin dependencies become watch inputs. |
| packages/…/index.ts | See how the self-contained executable exposes Tailwind assets, APIs, and plugin loading. |
| packages/…/build.ts | See the supported platform artifact set and checksum output. |
| integrations/…/index.test.ts | See the end-to-end contract for files, streams, watch modes, source maps, and dependency recovery. |
| integrations/…/standalone.test.ts | See the standalone executable contract for self-exclusion and first-party plugin use. |