skip to content

In Tailwind CSS v4, why do components from a shared UI package installed in node_modules render unstyled, and what fixes it?

level: middleimportance: should knowfreq 14%

answer

  1. automatic detection has exceptions
  2. the default skip list
  3. dependencies ignored since 4.1
  4. register a path explicitly
  5. relative to the stylesheet

basics

~20 s

Tailwind CSS v4's automatic source detection skips node_modules, so classes used only inside an installed package are never generated. Register it with @source "../node_modules/@clinic/ui" in the stylesheet that imports Tailwind; the path is relative to that stylesheet.

solid answer

~40 s

In Tailwind CSS v4, automatic detection scans every file from the base directory except files in `.gitignore`, the `node_modules` directory, binary files, CSS files and package-manager lock files. A shared package installed under `node_modules` is therefore never read, so utilities used only by its components are missing; anything the app also uses still appears, which makes the breakage look random. The fix is `@source "../node_modules/@clinic/ui";` in the stylesheet that imports Tailwind, with the path written relative to that stylesheet. Point at the package, not all of `node_modules`. Since 4.1.0 `node_modules` is ignored by default regardless of `.gitignore`, and an `@source` path inside it overrides that. The package must still ship complete class names, and any custom colors it uses must exist in the app's theme.

code

css · 5 lines
css
/* src/app.css in the dashboard app */
@import "tailwindcss";

/* The shared component package installed by the package manager */
@source "../node_modules/@clinic/ui";

go deeper

for a junior

Recall that Tailwind v4 skips node_modules when it looks for class names, so a component package needs an @source line in your stylesheet.

for a middle

Explain the default skip list, that @source paths resolve from the stylesheet, and why the package must ship complete class names that exist in the app's theme.

for a senior

Diagnose partial styling as a scanning gap rather than a cascade problem, scope @source to one package, and know the 4.1.0 changes to node_modules and symlinks.

for a principal

Decide how a shared component package tells consuming apps what to scan and which theme it expects, so each app's setup stays a documented one-liner instead of tribal knowledge.

## What automatic source detection scans In Tailwind CSS v4 there is no list of content globs to maintain. When a stylesheet contains `@import "tailwindcss";`, the scanner walks the project from a **base directory** (by default the working directory the build runs in; for the Vite plugin, Vite's `root`, which itself defaults to the working directory) and reads every file it meets as plain text, collecting the class names it finds. Utilities are generated only for those names. Automatic means *automatic with exceptions*. Some files are skipped by default because scanning them would be slow, pointless or noisy. ## What it skips by default | Skipped by default | Example | Why it is skipped | |---|---|---| | Files matched by `.gitignore` | build output, generated folders | usually not source the app authors | | The `node_modules` directory | every installed dependency | very large and mostly unrelated to your markup | | Binary files | images, videos, zip archives | there is no text to scan | | CSS files | `*.css` | they are not scanned for class names | | Common package-manager lock files | `package-lock.json`, `pnpm-lock.yaml` | noise that only resembles class names | The `node_modules` rule changed inside v4. Before **4.1.0** the folder was normally skipped only because `.gitignore` listed it; since 4.1.0 it is ignored by default whatever `.gitignore` says, and an `@source` rule can override that. This is why the clinic dashboard's shared component package, `@clinic/ui`, renders unstyled. Its buttons and badges carry class names in their files, but those files sit in `node_modules`, the scanner never reads them, and the utilities they need are never generated. Any utility the app itself also uses still appears, which makes the breakage look random: some parts of a component styled, others not. ## Registering the package with `@source` `@source` explicitly registers a path for the scanner: ```css /* src/app.css in the dashboard app */ @import "tailwindcss"; @source "../node_modules/@clinic/ui"; ``` Points that matter in practice: - The path is **relative to the stylesheet** that contains the directive, not to the project root or the directory the build runs in. - Point at the **one package**, not at `node_modules` as a whole. Scanning every dependency slows the build, and any token in a dependency that happens to match a utility gets generated. - Since 4.1.0, an `@source` path that points inside `node_modules` no longer considers your `.gitignore` rules, so the explicit registration wins. - Since 4.1.0, symlinks are followed when an `@source` path is resolved, which matters when a workspace package is linked into `node_modules`. - `@source` sits at the top level of the stylesheet and its path is quoted; Tailwind reports an error for a nested or unquoted `@source`. ## What the package itself must provide 1. **Complete class strings** in whatever it ships. Compiled JavaScript in a `dist` folder is fine, because the scanner reads text: a minified file that contains `"bg-emerald-600"` is as good as the original source. A package that assembles class names from fragments breaks in exactly the way an app does. 2. **Classes that resolve against the app's theme.** If the package uses a color the default theme lacks, such as `bg-sage-600`, the scanner finds the token but Tailwind discards it unless the app's theme defines that color. ## How this differs from v3 In Tailwind v3 a `tailwind.config.js` file carried a `content` array of globs, and scanning a dependency meant adding its path to that array. In v4 configuration is CSS-first: detection is automatic, and `@source` adds what detection skips. Loading a legacy JavaScript config is a separate concern from scanning. ## Choosing what the package should ship A package author can make the consuming side easier. Shipping the source files (or a build that keeps class strings intact) is enough for scanning; documenting the one `@source` line consumers need, and the theme colors the components expect, turns a confusing half-styled screen into a one-line setup step. A package that instead ships its own prebuilt utility CSS can leave the app loading a second copy of utilities it already generates. ## Diagnosing a component that renders unstyled - Inspect an affected element: the class is in the markup but DevTools lists no rule for it. - Search the built CSS for one class that only the package uses. - Check which stylesheet carries `@import "tailwindcss"` and resolve the `@source` path from that file's folder. - Confirm the installed version of the package actually contains complete class names in the files it ships.

  • Why not simply write `@source "../node_modules"` and cover every package at once?
    Because the scanner would read every dependency as text. Builds get slower, and any token in any dependency that happens to match a utility is generated, so the CSS grows with code you never render. Register the one package that carries Tailwind classes.
  • In a workspace, `node_modules/@clinic/ui` is a symlink to `packages/ui`. Does `@source` follow it?
    Yes, in current v4 releases: since 4.1.0 Tailwind follows symlinks when it resolves an `@source` path. Pointing `@source` straight at the workspace folder, such as `../../packages/ui/src`, works as well and makes the dependency on source files explicit.
  • The package's badges use `bg-sage-600`, a color the app never defines. What happens after you add `@source`?
    The scanner now finds the token, but Tailwind discards it because no utility matches without a `sage` color in the app's theme. The app has to define the colors the package expects, for example by importing a theme stylesheet the package provides.

  • Tailwind v4 scans node_modules unless you list it in .gitignore.
  • Add the package path to the content array in tailwind.config.js.
  • Point @source at the whole node_modules folder to be safe.
  • @source paths are resolved from the project root.
  • A package that ships compiled JavaScript hides its classes from the scanner.

Assumes Tailwind CSS v4 (4.3.3); node_modules is ignored by default since 4.1.0 and @source replaces v3's content globs.