Tailwind Config Validator#

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#

FlagDescription--strictTreat warnings as errors — exit code 1 (CI-friendly)--format textHuman-readable output (default)--format jsonMachine-readable JSON--format summaryCompact summary with counts

Validation Rules (26)#

Structure (5)#

RuleSeverityDescriptionS1errorFile not found or unreadableS2errorEmpty config fileS3errorInvalid JSON syntaxS4warning/infoUnknown top-level keys (valid: content, theme, plugins, presets, darkMode, prefix, important, separator, corePlugins, safelist, blocklist, future, experimental)S5infoJS/TS config detected (hint to export as JSON)

Content (5)#

RuleSeverityDescriptionC1errorMissing content paths (required for tree-shaking)C2warningEmpty content arrayC3warningContent paths include node_modules (performance)C4warningContent glob too broad (e.g. **/* without extension filter)C5infoSuspicious content pattern (bare *.css or similar)

Theme (5)#

RuleSeverityDescriptionT1warningOverriding entire theme key without extend (replaces defaults)T2infoEmpty theme.extend objectT3warningInvalid color values (not strings)T4infoReferencing default theme without callback (theme() needed)T5warningCustom screen breakpoints not in ascending order

Dark Mode (2)#

RuleSeverityDescriptionD1errorInvalid darkMode valueD2infodarkMode "class" deprecated in v3.4+ (use "selector")

Plugins (3)#

RuleSeverityDescriptionP1infoEmpty plugins arrayP2errorPlugins not an arrayP3infoDeprecated official plugins (built-in in v4)

Best Practices (6)#

RuleSeverityDescriptionB1errorNo content paths defined (tree-shaking broken)B2warningUsing important: true globally (anti-pattern)B3warningPrefix with special charactersB4warningcorePlugins disabled entirelyB5warningLarge safelist (>50 patterns, bloats CSS)B6warningMissing theme.extend (all customizations override defaults)

Exit Codes#

CodeMeaning0No errors (warnings allowed unless --strict)1Errors found (or warnings in --strict mode)2File 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