Tailwind 4 Validator
Purpose
Ensures:
- Projects use Tailwind v4 CSS-first configuration
- Old
tailwind.config.jspatterns are detected and flagged - Proper
@themeblocks are used instead of JS config - Dependencies are v4+
When to Use
- Before any Tailwind work: Run validation first
- New project setup: Ensure v4 is installed correctly
- After AI generates Tailwind code: Verify no v3 patterns snuck in
- Auditing existing projects: Check for migration needs
- CI/CD pipelines: Prevent v3 regressions
Quick Start
python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --suggest-fixes
python3 scripts/validate.py --root . --strict
What Gets Checked
| Check | Good (v4) | Bad (v3) |
|---|---|---|
| Package version | "tailwindcss": "^4.0.0" | "^3.4.0" |
| CSS config | @import "tailwindcss"; + @theme { --color-primary: ...; } | @tailwind base/components/utilities; |
| Config files | none - config lives in CSS | tailwind.config.{js,ts,mjs,cjs} (deprecated in v4) |
| PostCSS | plugins: { '@tailwindcss/postcss': {} } only | tailwindcss + autoprefixer as separate plugins |
| Imports | @import "tailwindcss/preflight" / .../utilities | @tailwind directives |
See references/full-guide.md (§ What Gets Checked, § Validation Output) for full GOOD/BAD examples and a sample validation report.
Migration Guide (v3 to v4)
- Swap packages: remove
tailwindcss/autoprefixer, addtailwindcss@latest+@tailwindcss/postcss - Point
postcss.config.jsat the@tailwindcss/postcssplugin only - Convert
tailwind.config.jstheme/extend values into an@theme { --color-*, --font-*, ... }block in CSS - Replace
@tailwinddirectives with@import "tailwindcss" - Delete
tailwind.config.{js,ts,mjs,cjs}
See references/full-guide.md (§ Migration Guide, § CI/CD Integration) for the exact before/after code per step and a CI workflow snippet.
Common v3 Patterns to Avoid
| v3 Pattern | v4 Replacement |
|---|---|
@tailwind base | @import "tailwindcss" |
@tailwind utilities | @import "tailwindcss/utilities" |
tailwind.config.js | @theme block in CSS |
theme.extend.colors | --color-* CSS variables |
theme.extend.spacing | --spacing-* CSS variables |
theme.extend.fontFamily | --font-* CSS variables |
content: ['./src/**/*.tsx'] | Not needed (auto-detected) |
plugins: [require('@tailwindcss/forms')] | @plugin "@tailwindcss/forms" |
See references/full-guide.md (§ v4 @theme Reference, § Using with shadcn/ui) for a full @theme token example and shadcn/ui token setup.
Troubleshooting
- "Found tailwind.config.js but using v4" - some tools still generate v3 configs. Delete the file and use
@themeinstead. - "@tailwind directives found" - replace with
@import "tailwindcss". The old directives are not supported in v4. - "autoprefixer in postcss.config" - remove autoprefixer; it's built into
@tailwindcss/postcss. - "content array in config" - v4 auto-detects content files. Remove the
contentconfig entirely.