Tailwind Config Validator

Validate JSON-exported Tailwind CSS configuration files for structural issues, content path problems, theme misconfiguration, and best practices. Use when auditing Tailwind configs, preparing production builds, or enforcing CI standards.

Validate Tailwind CSS configuration files exported as JSON for structural correctness, content path issues, theme misconfiguration, dark mode problems, plugin hygiene, and best practices. Pure Python 3 stdlib — no external dependencies.

Note: Tailwind configs are JS/TS, not directly parseable. This validator works with JSON-exported configs. Export via:

bash

node -e "console.log(JSON.stringify(require('./tailwind.config.js')))" > config.json
python3 scripts/tailwind_config_validator.py validate config.json

Commands

validate — Full validation with all rules

bash

python3 scripts/tailwind_config_validator.py validate config.json
python3 scripts/tailwind_config_validator.py validate config.json --strict
python3 scripts/tailwind_config_validator.py validate config.json --format json

lint — Run all rules (alias for validate)

bash

python3 scripts/tailwind_config_validator.py lint config.json
python3 scripts/tailwind_config_validator.py lint config.json --format summary
python3 scripts/tailwind_config_validator.py lint config.json --strict --format json

content — Check content configuration

bash

python3 scripts/tailwind_config_validator.py content config.json
python3 scripts/tailwind_config_validator.py content config.json --format json
python3 scripts/tailwind_config_validator.py content config.json --format summary

theme — Check theme configuration

bash

python3 scripts/tailwind_config_validator.py theme config.json
python3 scripts/tailwind_config_validator.py theme config.json --format json
python3 scripts/tailwind_config_validator.py theme config.json --format summary

Flags

Flag	Description
--strict	Treat warnings as errors — exit code 1 (CI-friendly)
--format text	Human-readable output (default)
--format json	Machine-readable JSON
--format summary	Compact summary with counts

Validation Rules (26)

Structure (5)

Rule	Severity	Description
S1	error	File not found or unreadable
S2	error	Empty config file
S3	error	Invalid JSON syntax
S4	warning/info	Unknown top-level keys (valid: content, theme, plugins, presets, darkMode, prefix, important, separator, corePlugins, safelist, blocklist, future, experimental)
S5	info	JS/TS config detected (hint to export as JSON)

Content (5)

Rule	Severity	Description
C1	error	Missing content paths (required for tree-shaking)
C2	warning	Empty content array
C3	warning	Content paths include node_modules (performance)
C4	warning	Content glob too broad (e.g. **/* without extension filter)
C5	info	Suspicious content pattern (bare *.css or similar)

Theme (5)

Rule	Severity	Description
T1	warning	Overriding entire theme key without extend (replaces defaults)
T2	info	Empty theme.extend object
T3	warning	Invalid color values (not strings)
T4	info	Referencing default theme without callback (theme() needed)
T5	warning	Custom screen breakpoints not in ascending order

Dark Mode (2)

Rule	Severity	Description
D1	error	Invalid darkMode value
D2	info	darkMode "class" deprecated in v3.4+ (use "selector")

Plugins (3)

Rule	Severity	Description
P1	info	Empty plugins array
P2	error	Plugins not an array
P3	info	Deprecated official plugins (built-in in v4)

Best Practices (6)

Rule	Severity	Description
B1	error	No content paths defined (tree-shaking broken)
B2	warning	Using important: true globally (anti-pattern)
B3	warning	Prefix with special characters
B4	warning	corePlugins disabled entirely
B5	warning	Large safelist (>50 patterns, bloats CSS)
B6	warning	Missing theme.extend (all customizations override defaults)

Exit Codes

Code	Meaning
0	No errors (warnings allowed unless --strict)
1	Errors found (or warnings in --strict mode)
2	File not found / parse error

CI Integration

yaml

# GitHub Actions example
- name: Validate Tailwind config
  run: |
    node -e "console.log(JSON.stringify(require('./tailwind.config.js')))" > /tmp/tw-config.json
    python3 scripts/tailwind_config_validator.py validate /tmp/tw-config.json --strict --format json

Example Output

text

tailwind.config validate — config.json
=======================================
[ERROR  ] C1: Missing 'content' paths — required for tree-shaking
         Without content paths, Tailwind cannot purge unused CSS. Add content: ['./src/**/*.{html,js,ts,jsx,tsx}'].
[WARNING] T1: theme.colors overrides all default colors — use theme.extend.colors instead
         Placing keys directly under 'theme' replaces the entire default set. Move to 'theme.extend' to merge with defaults.
[WARNING] B2: important: true applies !important to all utilities (anti-pattern)
         Prefer important: '#app' to scope specificity to a root selector instead of global !important.
[INFO   ] P3: Plugin '@tailwindcss/forms' is built-in since Tailwind v4
         In Tailwind v4, @tailwindcss/forms functionality is included by default. Remove the plugin if upgrading.
[INFO   ] D2: darkMode 'class' is deprecated since v3.4 — use 'selector' instead
         The 'class' strategy still works but 'selector' is the recommended replacement.

Result: INVALID
Summary: 1 error(s), 2 warning(s), 2 info