PostCSS Config Validator
Validate .postcssrc, .postcssrc.json, postcss.config.js, postcss.config.ts, and package.json#postcss for deprecated plugins, ordering issues, Tailwind integration problems, parser misconfiguration, and best practices. JS/TS configs are detected but cannot be statically validated. Supports text, JSON, and summary output formats with CI-friendly exit codes.
Commands
# Full validation (all 22+ rules)
python3 scripts/postcss_config_validator.py validate .postcssrc
# Quick structure-only check
python3 scripts/postcss_config_validator.py check .postcssrc.json
# Explain config in human-readable form
python3 scripts/postcss_config_validator.py explain package.json
# Suggest improvements
python3 scripts/postcss_config_validator.py suggest .postcssrc
# JSON output (CI-friendly)
python3 scripts/postcss_config_validator.py validate .postcssrc --format json
# Summary only (pass/fail + counts)
python3 scripts/postcss_config_validator.py validate .postcssrc --format summary
# Strict mode (warnings and infos become errors)
python3 scripts/postcss_config_validator.py validate .postcssrc --strict
Rules (22+)
| # | ID | Category | Severity | Rule |
|---|---|---|---|---|
| 1 | S1 | Structure | Error | File not found or unreadable |
| 2 | S2 | Structure | Error | Empty config file |
| 3 | S3 | Structure | Error | Invalid JSON syntax |
| 4 | S4 | Structure | Warning | Unknown top-level keys (valid: plugins, parser, syntax, stringifier, map, from, to) |
| 5 | S5 | Structure | Info | JS/TS config detected — cannot statically validate |
| 6 | P1 | Plugins | Warning | Empty plugins object/array |
| 7 | P2 | Plugins | Warning | Deprecated plugin (autoprefixer-core, postcss-cssnext, lost, postcss-sprites) |
| 8 | P3 | Plugins | Warning | Duplicate plugins |
| 9 | P4 | Plugins | Info | Plugin ordering issues (autoprefixer after preset-env, cssnano last) |
| 10 | P5 | Plugins | Info | postcss-import should be first plugin |
| 11 | P6 | Plugins | Info | Unknown/uncommon plugin name (not in top 50 list) |
| 12 | T1 | Tailwind | Info | tailwindcss without nesting plugin |
| 13 | T2 | Tailwind | Warning | tailwindcss after autoprefixer (wrong order) |
| 14 | T3 | Tailwind | Info | postcss-preset-env with tailwindcss (potential conflict) |
| 15 | X1 | Syntax/Parser | Warning | Both parser and syntax specified |
| 16 | X2 | Syntax/Parser | Info | Unknown parser value |
| 17 | X3 | Syntax/Parser | Info | Parser set but no matching preprocessor plugin |
| 18 | M1 | Source Maps | Info | Source maps disabled (map: false) |
| 19 | M2 | Source Maps | Info | Inline source maps enabled (map.inline: true) |
| 20 | B1 | Best Practices | Warning | No plugins configured |
| 21 | B2 | Best Practices | Info | Using postcss-preset-env AND individual feature plugins it includes |
| 22 | B3 | Best Practices | Info | Very large number of plugins (>15) |
Output Formats
text(default): Human-readable with severity iconsjson: Machine-parseable JSON with findings array and summarysummary: Pass/fail with error/warning/info counts
Exit Codes
0: No errors (warnings/infos only or clean)1: One or more errors found2: File not found or invalid input
Requirements
- Python 3.8+
- No external dependencies (pure stdlib)