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 / content-discovery-and-scanning

Content discovery and scanning

Content discovery and scanning finds the project files that may contain Tailwind class candidates and supplies those candidates to the CSS compiler. JavaScript code defines the compilation contract and build flow. The Rust Oxide scanner resolves source boundaries, reads and prepares files, extracts candidates, and keeps enough state to support fast rebuilds.

Discovery model

Source roots

The compiler turns authored CSS into a set of source rules. A source rule has a base path, a pattern relative to that path, and an optional negation. The compiler gets these rules from @source directives and from the root passed to @tailwind utilities source(…).

If CSS does not set a source root, the JavaScript build surfaces use the working or input base with a recursive pattern. source(none) disables automatic discovery. An explicit root limits discovery to the selected path, while additional @source rules extend or exclude that scope. The Node compile service checks the fixed part of an explicit root before it returns the compiler, so a missing source directory fails early instead of producing an empty scan. This lets the CSS input control which parts of a project can affect generated utilities.

References: packages/…/index.ts• L107-115 packages/…/index.ts• L174-220 packages/…/index.ts• L257-305 packages/…/index.ts• L288-301 packages/…/compile.ts• L66-103

Source policies

The scanner applies each source rule as a policy before it reads content. It distinguishes automatic project sources, explicit patterns, ignored patterns, and external sources. Automatic sources use the scanner's normal ignore rules. Explicit sources can include files that those rules would otherwise omit. External sources bypass the normal ignore rules but still reject binary content.

The policy also accounts for repository .gitignore files and common non-content directories, files, and extensions. Brace patterns are expanded and fixed path parts move into the base path before walking. Narrow patterns add the inverse directory rules needed to reach matching nested files without opening the whole parent tree.

References: crates/…/auto_source_detection.rs• L4-27 crates/…/sources.rs• L22-63 crates/…/sources.rs• L718-848 crates/…/mod.rs• L709-846

Watch boundaries

Source discovery produces two related views. The scanner uses resolved files and optimized globs to read current content. Build tools use those same files and globs as dependency boundaries so a matching file change can trigger a rebuild without watching the whole project.

The generated watch boundaries are narrower than a raw project-wide glob when the scanner can prove that only certain directories or extensions matter. The scanner also tracks directories needed to notice new matching files. In the CLI, native file watching subscribes to the directories derived from normalized sources, while polling checks the scanner's current file view. This connects source selection to both candidate accuracy and rebuild cost.

References: crates/…/mod.rs• L264-313 crates/…/detect_sources.rs• L31-159 packages/…/index.ts• L330-342 packages/…/index.ts• L604-620 packages/…/index.ts• L850-866

Candidate extraction

File preparation

After source selection, the scanner reads eligible files and prepares their text for candidate extraction. File extensions select optional pre-process steps for template formats such as Vue, Svelte, Markdown, Pug, Ruby, and Rust. The Pug step keeps class shorthand and class text visible while protecting attribute values, quoted text, and bracketed utility values from false changes. Files without a special pre-process step pass through unchanged.

CSS files follow a separate path. The scanner does not treat all CSS text as template content. It extracts CSS variables that are used by the generated design system instead. This keeps source candidates and CSS variable usage as separate inputs to compilation.

References: crates/…/mod.rs• L450-510 crates/…/mod.rs• L541-560 crates/…/mod.rs• L578-620 crates/…/pug.rs• L10-211

Candidate recognition

A class candidate is a string that looks like a Tailwind utility or variant expression in source text. Oxide scans prepared text with an extractor that recognizes complete candidates, nested candidates inside bracketed expressions, and used CSS variables. It returns raw strings rather than generated CSS.

Candidate recognition uses valid boundaries and the relationship between variants and utilities. This rejects malformed or joined text while still finding candidates inside arrays, object-like syntax, and bracketed content. When a larger candidate covers an inner span, the extractor keeps the outer candidate and avoids duplicate covered spans. The compiler receives these strings and decides which ones are valid for the active theme and utility set.

This separation allows the scanner to search many source languages without needing to understand the final CSS meaning of every candidate.

References: crates/…/candidate_machine.rs• L8-23 crates/…/candidate_machine.rs• L45-205 crates/…/mod.rs• L24-36 crates/…/mod.rs• L56-145 crates/…/mod.rs• L184-275 crates/…/mod.rs• L233-262

Candidate identity

The scanner stores candidates in a unique set. A full scan returns the complete set in stable sorted order. Later scans return only candidates that the scanner has not seen before, so repeated files do not send duplicate work to the compiler.

The compiler keeps its own valid-candidate set and treats new candidates as additions to the generated utility output. This incremental contract is monotonic: a changed or removed source file cannot remove an already generated rule through a candidate-only update. Build tools must request a full rebuild when the source or CSS state needs to be reconstructed.

References: crates/…/mod.rs• L58-93 crates/…/mod.rs• L123-135 crates/…/mod.rs• L233-262 packages/…/index.ts• L730-817

Incremental compilation

Initial scan

An initial build creates a compiler and a scanner from the same CSS-derived source rules. The scanner walks the allowed roots, records files and extensions, prepares changed content, extracts candidates, and returns the complete candidate set. The compiler then builds generated CSS from that set.

The first walk uses a low-overhead synchronous path. It records file modification times for later comparisons and records the files and directories that define the current source view. The result becomes the scanner's baseline for watch mode.

This diagram shows how authored CSS and project files meet at the compiler boundary.

flowchart LR
    CSS[Authored CSS] --> Compiler[JavaScript compiler]
    Compiler --> Rules[Source rules]
    Rules --> Scanner[Rust Oxide scanner]
    Files[Project files] --> Scanner
    Scanner --> Candidates[Class candidates]
    Candidates --> Compiler
    Compiler --> Output[Generated CSS]

References: packages/…/index.ts• L278-327 packages/…/index.ts• L502-517 crates/…/mod.rs• L123-135 crates/…/mod.rs• L375-518

Changed content scans

During an incremental rebuild, a build tool passes changed files or raw content to the scanner. Raw content can be scanned directly. A changed file is accepted when it was already in the discovered file set or when it matches the configured source walk. The scanner canonicalizes changed file paths and compares them with walked paths so symlinked files remain inside the configured source boundary. It then prepares only that content and returns new candidates.

The CLI groups file events before it selects a rebuild strategy. Changes to the input CSS or tracked configuration and plugin dependencies cause a full rebuild that recreates the compiler and scanner. Other changes become extension-tagged content entries for an incremental scan. In polling mode, the CLI first refreshes the scanner's file view and uses its scanned files to make the same choice. If no new candidates appear, it keeps the current output.

For repeated directory scans, modification times allow unchanged files to be skipped. A full rebuild resets the compiler and scanner when source rules, CSS dependencies, or file changes make the old candidate set unsafe to reuse. An incremental build can then send only newly found candidates to the existing compiler.

References: crates/…/mod.rs• L137-231 crates/…/mod.rs• L404-519 packages/…/index.ts• L337-429 packages/…/index.ts• L538-570 packages/…/index.ts• L604-648 packages/…/index.ts• L800-822

Compiler handoff

The JavaScript compiler accepts the scanner's raw candidate strings through its build operation. It filters invalid candidates, retains valid candidates across builds, and regenerates utility rules only when the candidate or related design-system state changes. If a scan finds no new candidates, the build surface can keep the existing CSS output.

This handoff is shared by the CLI and build-tool adapters. The adapters decide when a rebuild is full or incremental. The compiler and scanner provide the source and candidate services that make either choice possible.

References: packages/…/index.ts• L730-817 packages/…/index.ts• L413-429 packages/…/index.ts• L223-247

JavaScript and Rust boundary

Native scanner interface

The @tailwindcss/oxide package exposes the Rust scanner to JavaScript through a Node-API binding. JavaScript supplies source entries or changed content. The binding maps them to the Rust types and exposes full scans, changed-content scans, discovered files, normalized sources, and watcher globs.

The binding does not decide which candidates become CSS. It carries source and content data into Oxide and carries extracted strings and watch information back to JavaScript. This keeps file walking and extraction in the native component while the compiler remains in the JavaScript package.

References: crates/…/lib.rs• L8-42 crates/…/lib.rs• L44-83 crates/…/lib.rs• L88-191 crates/…/lib.rs• L1-12

Integration services

The CLI, Vite, PostCSS, Webpack, and Turbopack surfaces build a scanner from the compiler's source data. They use scanner files as direct dependencies and scanner globs as broader watch rules. They then pass scanner results into the compiler during their own build or rebuild cycle.

The scanner therefore has two downstream roles: it supplies candidate strings for CSS generation and it describes the file boundaries that the host build system must observe. The Node compile service also resolves JavaScript and CSS dependencies used by compilation. It first gives host-provided resolvers a chance to handle a request, then uses standard Node-oriented resolution rules and reports loaded files as dependencies. For the Node-facing compiler and scanner services, see Node API and compilation. For the native extraction contract, see Oxide scanner and native bindings. For path rules and glob behavior, see Source resolution and globbing. For generated CSS behavior, see Compiler and CSS generation. For host-specific build behavior, see Build tool integrations.

References: packages/…/index.ts• L394-485 packages/…/index.ts• L249-284 packages/…/index.ts• L186-229 packages/…/compile.ts• L33-64 packages/…/compile.ts• L121-177 packages/…/compile.ts• L213-284

Change checklist

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

  • Changes to @source parsing or compiler root semantics must stay aligned with the source-entry mapping used by every scanner-creating integration.
  • Changes to candidate accumulation or removal semantics must be checked against the rebuild strategy. Candidate-only updates assume that the existing compiler state remains valid.
  • Changes to scanner file and glob reporting must preserve the dependency contracts used by CLI watchers and build-tool adapters.
  • Changes to the JavaScript binding's ChangedContent, SourceEntry, or scanner method shapes must stay aligned with the generated Node-API types and all JavaScript consumers.
  • Changes to extension pre-processing must preserve the extension names passed by full scans and changed-content scans.
  • Changes to CLI rebuild-path tracking must preserve the split between full rebuilds for CSS and configuration dependencies and incremental scans for content files.
  • Changes to CLI watcher setup must keep output and source-map files out of the rebuild loop in both event and polling modes.
  • Changes to module or stylesheet resolution must preserve dependency reporting and the resolver order used by host integrations.

Important failure modes

TriggerConsequenceGuard
A source root is wrong or does not existThe scanner reads the wrong project area or cannot start the intended scanThe Node compiler service checks the non-glob part of an explicit source root before returning the compiler.
A needed file is outside automatic discovery or is covered by an ignore ruleClasses in that file do not reach the compilerAdd an explicit @source rule. Explicit and external source policies are handled separately from automatic ignores.
A source rule narrows a directory without preserving its parent pathsMatching nested directories cannot be reached during the walkSource normalization adds the required inverse path rules before the scanner builds its walker.
A source file is removed but the host keeps an incremental compilerCSS can retain a rule that no longer has a source candidateUse the host's full rebuild path when file state or source configuration changes.
A CSS, config, plugin, or imported stylesheet changes but the CLI treats it as contentThe existing compiler can keep stale theme or source stateKeep tracked full-rebuild paths separate from extension-tagged changed content.
The native scanner cannot read a changed fileThe file contributes no new candidates and the rebuild may appear unchangedCheck scanner read errors and use a full rebuild when the source state cannot be trusted.
The output or map file is included in the scan boundaryGenerated output can trigger self-rebuild loops or add false candidatesBuild surfaces exclude their output artifacts from watch and scan handling.
The file watcher cannot load on the current platformEvent-based watch mode cannot startUse polling mode when the native file watcher is unavailable.
A module or stylesheet cannot be resolvedCompilation stops and the dependent output is not producedUse the host resolver or a valid Node-compatible path, and surface the resolution error.

Key files

FileWhy to read it
packages/…/index.tsDefines how CSS source directives become source rules and how candidate strings enter incremental compilation.
packages/…/compile.tsDefines the Node compile boundary, source-root validation, dependency reporting, and JavaScript or CSS module resolution.
crates/…/mod.rsShows the end-to-end native scan lifecycle from source walking through preprocessing, extraction, and candidate state.
crates/…/sources.rsExplains source categories, path normalization, explicit exclusions, and external source behavior.
crates/…/detect_sources.rsShows how discovered directories and extensions become watch-friendly glob boundaries.
crates/…/mod.rsDefines the native extractor's candidate and CSS-variable output, including nested candidate handling.
crates/…/candidate_machine.rsDefines how variants, utilities, and source boundaries become complete candidate spans.
crates/…/pug.rsShows how Pug syntax is prepared so class shorthand and attribute content can be scanned without losing utility candidates.
crates/…/lib.rsDefines the JavaScript-facing scanner and changed-content contract.
packages/…/index.tsIllustrates initial scans, full rebuilds, incremental scans, event watching, polling, and watcher setup in one build surface.
packages/…/index.tsIllustrates how scanner files and globs become host dependency messages.
packages/…/index.tsIllustrates scanner reuse, candidate accumulation, and build-tool watch registration.