Skill Details
Runtime
(claude-5-sonnet)
Example user message
[userMessage]: "I just migrated my Vite React project from Tailwind v3 to v4. Everything works, but my production CSS jumped from about 4KB to over 80KB! I am using a few components from shadcn-ui. My `app.css` uses `@import "tailwindcss";` and I added `@source "../node_modules";` just to make sure the UI library styles loaded properly. Can you help me get my file size back down?"
Example agent response
Found it — the culprit is this line:
```css
@source "../node_modules";
```
**Root cause:** In Tailwind v4, `@source` tells the Oxide engine to scan those files for class names to generate. Pointing it at the entire `node_modules` directory makes it scan *every* JS/TS/HTML file in every package you've installed — including packages that have nothing to do with your UI. Any string in any of those files that happens to look like a valid Tailwind utility (`text-sm`, `flex`, `p-4`, etc.) gets generated into your CSS. That's almost certainly your jump from 4KB to 80KB+.
You don't need to scan `node_modules` at all — shadcn-ui components aren't styled by scanning the library's source; they're **copied into your own project** (usually `src/components/ui/`), so Tailwind already picks them up when it scans your app's source files.
### Fix
Remove the broad `@source` directive entirely:
```css
@import "tailwindcss";
/* Remove this line: */
/* @source "../node_modules"; */
```
If your `@import "tailwindcss";` is at the root of your CSS and your `app.css` lives inside `src/`, Tailwind v4's automatic content detection should already pick up everything under your project root (excluding `.gitignore`d paths like `node_modules`, `dist`, etc. by default). You likely don't need any manual `@source` directive at all.
**Only add `@source` back if:**
- You have shadcn/ui or other component files living *outside* the default scan root (e.g., a monorepo package), in which case scope it precisely:
```css
@source "../../packages/ui-components/**/*.{ts,tsx}";
```
- Never point `@source` at `node_modules` as a whole — if you truly need one specific package's compiled output scanned (rare), target the exact subpath, e.g. `@source "../node_modules/some-specific-package/dist";`.
### Verify
```bash
npm run build
```
Check the new CSS file size — it should drop back down near your original ~4KB (plus whatever shadcn-ui components you're actually using). Do a quick visual pass on the pages using shadcn-ui components to confirm nothing broke, since shadcn relies on CSS variables (`--background`, `--primary`, etc.) defined in your `@theme` block — those aren't affected by this fix, just the utility-class bloat.
If size is still high after removing that line, the next place I'd check is whether your `@theme` block has leftover unused CSS variables from the v3→v4 migration — happy to take a look at that file if you want a second pass.
By purchasing this skill, you agree to our terms of service
CLAUDE-5-SONNET
A diagnostic tool that identifies and resolves Tailwind CSS production build bloat. It analyzes your configuration files across Tailwind v3 and v4 to fix tree-shaking issues, misconfigured content paths, and UI library bloat, shrinking production CSS back to optimal sizes (typically under 5KB).
...more
Added 1 week ago
