Source resolution and globbing
Source resolution decides which files Tailwind CSS should consider before the content scanner reads them. It combines a default project view with CSS source directives, applies path and ignore rules, and produces a bounded set of files and watch patterns for candidate extraction. For the wider scan flow, see Content discovery and scanning.
Resolution pipeline
The resolution pipeline turns the CSS entry point and its source directives into scanner roots. It keeps source selection separate from candidate extraction, so a file that is not selected here cannot add a class candidate later.
The main stages are:
- Read the source mode from the compiled CSS.
- Add automatic or explicit filesystem sources.
- Expand and normalize each path pattern.
- Apply built-in rules, project
.gitignorerules, and source exclusions. - Walk only the resulting roots and pass selected files to the scanner.
This flow connects the CSS compiler to the native scanner. The Node API and build tool adapters create the scanner from the compiler's resolved root and source list. See Node API and compilation services for the service layer and Oxide scanner and native bindings for the scan step.
flowchart LR
CSS[CSS entry point] --> Mode{Source mode}
Mode -->|No source override| Auto[Automatic project source]
Mode -->|source(path)| Root[Explicit source root]
Mode -->|source(none)| None[No automatic source]
CSS --> Directives[@source directives]
Auto --> Normalize[Expand and normalize paths]
Root --> Normalize
Directives --> Normalize
Normalize --> Rules[Apply ignore and include rules]
Rules --> Walk[Walk bounded filesystem roots]
Walk --> Files[Selected files and watch globs]
Files --> Scan[Content scanning]
Source modes
Automatic source detection
Automatic source detection starts at the build base when the CSS does not set a source root. In the CLI and build plugins, that means a recursive **/* source rooted at the working directory or the input CSS directory. The scanner then narrows that view to useful source files and records the directories needed for later watch updates.
Automatic detection is disabled by source(none). This mode is useful when the CSS should only use explicitly named sources or inline candidates. An explicit source("...") replaces the automatic root with the named path while @source entries remain additional sources.
References: packages/…/index.ts• L419-432 packages/…/index.ts• L288-301 packages/…/index.ts• L223-239 packages/…/index.ts• L192-216
Explicit source configuration
The @source directive names a file, folder, or glob that must take part in source selection. Its path is resolved from the CSS context, so a nested stylesheet can name sources relative to its own location. A directory means recursive source detection; a file or glob limits the selected paths.
The not form removes a path from the selected set. The inline(...) form does not read the filesystem. It adds known candidate names directly to compilation, or removes them when used with not, and therefore bypasses file discovery.
Explicit patterns are checked against each walked file after path normalization. This keeps a narrow source from selecting unrelated files under the same walk root, while the walk rules still keep the directories needed to reach matching wildcard paths.
| CSS form | Source-selection effect |
|---|---|
No source(...) option | Recursively inspect the default build base. |
source("path") | Use path as the automatic source root. |
source(none) | Do not add an automatic source root. |
@source "path-or-glob" | Add a filesystem source. |
@source not "path-or-glob" | Exclude matching files from the source set. |
@source inline("candidate") | Add a candidate without reading a file. |
References: packages/…/index.ts• L192-216 packages/…/index.ts• L257-307 crates/…/mod.rs• L866-906 crates/…/sources.rs• L141-235 packages/…/index.test.ts• L3822-3862
Glob expansion
Pattern normalization
The scanner accepts each source as a base directory plus a pattern. Before walking, it expands brace expressions such as {pages,components} into separate paths, moves fixed path segments into the base directory, and canonicalizes the result. A directory becomes **/*; a fixed file stays as a file pattern; a wildcard remains in the pattern.
This normalization gives the walker a smaller filesystem area to inspect. It also makes equivalent relative, absolute, and parent-relative paths use the same canonical source model. Invalid or unresolved fixed bases cannot produce a usable glob.
References: crates/…/sources.rs• L238-343 crates/…/sources.rs• L718-763
Automatic glob generation
For an automatic source, the scanner builds watch globs from the directories it finds. It uses known template extensions and adds extensions discovered in the project. It uses deep recursive globs where a directory is safe to watch as a whole, shallow globs where nested directories need separate tracking, and direct file tracking for the public directory because it can contain both source and generated output.
The generated globs serve two related needs. They describe the files that can enter a scan, and they let build tool integrations invalidate a build when a new matching file appears. Explicit source patterns stay explicit, so a narrow source does not silently become a scan of its parent directory.
References: crates/…/detect_sources.rs• L10-18 crates/…/detect_sources.rs• L41-59 crates/…/detect_sources.rs• L60-160 crates/…/glob.rs• L68-133 packages/…/index.ts• L466-501
Ignore handling
Built-in exclusions
Automatic detection avoids paths that usually do not contain authored templates. The default rules exclude common tool and dependency directories such as .git, .next, .turbo, and node_modules. They also exclude known non-template extensions, common lock and environment files, and binary file types.
These rules protect scan time and prevent generated or binary data from producing false candidates. They apply to automatic source detection. An explicitly named source can opt into an otherwise ignored location through the explicit-source rules.
| Exclusion group | Examples |
|---|---|
| Content directories | .git, .next, .turbo, node_modules |
| Non-template files | less, sass, scss, styl, log |
| Common project files | package-lock.json, pnpm-lock.yaml, bun.lockb, .env |
| Binary files | Images, archives, executables, and other known binary extensions |
References: crates/…/auto_source_detection.rs• L4-27 crates/…/auto_source_detection.rs• L30-71 crates/…/ignored-content-dirs.txt• L1-15 crates/…/ignored-extensions.txt• L1-6 crates/…/ignored-files.txt• L1-6
Explicit inclusion and exclusion
Explicit source paths have higher intent than automatic filtering. A named file can be scanned even when a built-in rule or a project ignore rule would normally omit it. A named directory inside an ignored location becomes an external source: the scanner opens that directory but still keeps binary-file exclusions.
Source exclusions are applied in source order. This lets a broad source include a tree and a later @source not entry remove a file or sub-tree. Narrow patterns also preserve the directory paths needed to reach their matches, without opening unrelated siblings.
References: crates/…/sources.rs• L43-63 crates/…/sources.rs• L141-235 crates/…/mod.rs• L727-772 crates/…/mod.rs• L838-906
Gitignore boundaries
The walker uses project .gitignore files as part of file selection. It does not use global Git ignore files. When a source is inside a Git repository, ignore lookup stops at that repository's root, so an unrelated .gitignore in a parent directory cannot change the project scan. When no repository exists, lookup stops at the current working directory boundary for source classification.
The walker still includes hidden files and follows symbolic links. Canonical paths are tracked as well as walked paths so a link and its target do not create two unrelated source identities.
References: crates/…/sources.rs• L765-841 crates/…/mod.rs• L776-827 crates/…/mod.rs• L403-449
Filesystem boundaries
Source roots
Every scan has at least one root when filesystem scanning is enabled. The first root becomes the main walk root, and other explicit roots are added as separate roots. This matters for sources outside the CSS base or inside ignored directories: the named root is opened directly instead of widening the main project walk.
The source base is canonicalized before pattern matching. A fixed part of a source path must resolve to a directory when it represents an automatic root. The Node compilation service checks the non-glob prefix of source(...) before it returns a compiler, while integrations also validate source roots when they register watch dependencies.
References: crates/…/mod.rs• L709-831 crates/…/sources.rs• L263-343 packages/…/compile.ts• L66-103 packages/…/index.ts• L241-257
Scan handoff
After resolution, the scanner exposes selected files, normalized sources, and generated globs to its callers. Build integrations use the file set for dependency tracking and the glob set for directory or file watches. The scanner then reads only changed selected files and sends their content to candidate extraction.
This boundary is why source mistakes usually appear as missing utility classes rather than compiler errors. If a path is outside every root, matches an exclusion, or is not covered by an explicit pattern, the later scanner has no content from which to recover it.
References: crates/…/mod.rs• L123-135 crates/…/mod.rs• L265-331 packages/…/index.ts• L303-324 packages/…/index.ts• L245-258
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to source mode parsing must stay aligned with the root handling in the CLI, PostCSS, and Vite scanner setup.
- Changes to built-in ignore lists must also preserve the distinction between ignored directories, ignored text extensions, common project files, and binary files.
- Changes to source normalization must preserve the base/pattern contract used by native scanning and by build-tool watch registration.
- Changes to explicit inclusion rules must preserve source order for
@source notand must not widen a restricted pattern to unrelated sibling directories. - Changes to Gitignore boundaries must keep repository-root limits consistent between source classification and the filesystem walker.
- Changes to generated glob shapes must be checked against both new-file detection and existing-file dependency registration.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
source(...) names a missing directory before its first glob segment | Compilation fails before source scanning starts. | The Node compile layer checks the fixed path prefix and reports the source path. |
| Automatic detection reaches a dependency, build, or binary-heavy directory | Scan cost rises and unrelated content can add candidates. | Built-in directory, file, extension, and binary rules filter the automatic walk. |
A needed file is covered by .gitignore but is not named explicitly | The file is not selected and its classes do not reach compilation. | Add an explicit @source path or use a source root that includes it. |
| A narrow source pattern lacks a reachable parent rule | The walker cannot reach a wildcard directory or scans the wrong sibling set. | Source normalization adds the required parent include rules and keeps restricted roots separate. |
| A source is outside the expected project root | The path may be skipped by a root-relative pattern or may widen the wrong watch area. | Canonicalize the source and inspect its normalized base and pattern before changing the scan. |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Defines source modes and collects @source filesystem and inline entries from CSS. |
| packages/…/compile.ts | Enforces the fixed-directory check for an explicit source root before callers create a scanner. |
| crates/…/sources.rs | Defines source kinds, path normalization, brace expansion, ignore promotion, and restricted-pattern behavior. |
| crates/…/auto_source_detection.rs | Defines the built-in exclusions used by automatic detection. |
| crates/…/detect_sources.rs | Turns discovered directories and extensions into efficient automatic watch globs. |
| crates/…/mod.rs | Builds the bounded walker, applies source and Gitignore rules, and exposes files and globs to integrations. |
| crates/…/glob.rs | Groups and optimizes normalized glob entries for scanning and file watching. |
| packages/…/index.ts | Shows how the CLI combines automatic roots, CSS sources, and CLI-specific exclusions before scanning. |
| packages/…/index.ts | Shows how a build tool uses resolved files and globs for candidate scans and watch updates. |