Tailwind CSS v4 auto-detection scoping uncertainty in monorepo builds

Recommendation

Do not trust Tailwind CSS v4 auto-detection as the sole source of truth for a multi-package repository. For repeatable CI output, pin explicit @source globs for every workspace package, or use @source none and declare every template file explicitly. Auto-detection is acceptable only when all packages share one repository root, .gitignore is committed and identical on every machine, and CI never performs a shallow clone.

Confirmed facts vs. likely explanation

Confirmed facts

• Tailwind CSS v4 replaces the v3 content array with CSS-first configuration and automatic content detection.
• The scanner walks from the CSS entry point's directory upward to locate a git root, then filters the tree using that root's .gitignore.
• @source inline("...") is the v4 replacement for v3 safelist, but it accepts string literals only; dynamic class names must be fully enumerated.
• @source none disables automatic scanning and forces explicit @source declarations.

Likely explanation and uncertainty

Packages outside the detected git root—such as sibling workspaces with independent .git folders or no .git at all—are not scanned unless explicitly included. A missing or divergent .gitignore can silently remove files from the scan and change the generated utility set. Shallow clones or CI checkouts that omit .git can break root detection and cause Tailwind to fall back to the CSS file's directory. These behaviors depend on the implementation and should be verified against your installed version before adoption.

Steps for this case

1. In your main CSS entry file, add one @source glob per workspace package:

@source "../../packages/design-system/**/*.{tsx,ts,jsx,js}";
@source "../../packages/web-app/**/*.{tsx,ts,jsx,js}";
@source inline("package-a-only package-b-only");

1. Place dynamic class strings in a dedicated safelist.css file imported by the main entry, mirroring the v3 safelist pattern.
2. In CI, capture the scanner's file list with verbose output and diff it against a committed manifest of expected workspace globs.
3. Add a temporary test template in each package containing a unique class name, build, and grep the output CSS to confirm the class appears.
4. Run the build twice in a clean container and diff the generated CSS; any difference indicates non-determinism.

Auditing generated CSS

Run the production build with verbose logging, redirect the scanned-file list to a text file, and compare it to a committed baseline. Any package missing from the list is a scanning gap. Do not rely on the presence of utility classes alone, because unused classes may not appear in output even when the file was scanned.

Maintenance overhead

Migrating from safelist to @source inline(...) adds maintenance because inline() cannot use template expressions. Every new dynamic class pattern must be enumerated or moved into a scanned template file. This overhead is the trade-off for repeatability: explicit declarations remove dependence on implementation-defined scanning.

Missing diagnostic detail

Do all workspace packages share a single repository root with a committed .git directory? If some packages use independent .git folders or none at all, auto-detection is unlikely to cover them reliably and explicit @source globs become mandatory.

Reviewer note: verify CLI verbose/debug flags and exact scan behavior against the installed Tailwind CSS v4 version before publishing.