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#

bash

# 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+)#

#IDCategorySeverityRule1S1StructureErrorFile not found or unreadable2S2StructureErrorEmpty config file3S3StructureErrorInvalid JSON syntax4S4StructureWarningUnknown top-level keys (valid: plugins, parser, syntax, stringifier, map, from, to)5S5StructureInfoJS/TS config detected — cannot statically validate6P1PluginsWarningEmpty plugins object/array7P2PluginsWarningDeprecated plugin (autoprefixer-core, postcss-cssnext, lost, postcss-sprites)8P3PluginsWarningDuplicate plugins9P4PluginsInfoPlugin ordering issues (autoprefixer after preset-env, cssnano last)10P5PluginsInfopostcss-import should be first plugin11P6PluginsInfoUnknown/uncommon plugin name (not in top 50 list)12T1TailwindInfotailwindcss without nesting plugin13T2TailwindWarningtailwindcss after autoprefixer (wrong order)14T3TailwindInfopostcss-preset-env with tailwindcss (potential conflict)15X1Syntax/ParserWarningBoth parser and syntax specified16X2Syntax/ParserInfoUnknown parser value17X3Syntax/ParserInfoParser set but no matching preprocessor plugin18M1Source MapsInfoSource maps disabled (map: false)19M2Source MapsInfoInline source maps enabled (map.inline: true)20B1Best PracticesWarningNo plugins configured21B2Best PracticesInfoUsing postcss-preset-env AND individual feature plugins it includes22B3Best PracticesInfoVery large number of plugins (>15)

Output Formats#

• text (default): Human-readable with severity icons
• json: Machine-parseable JSON with findings array and summary
• summary: Pass/fail with error/warning/info counts

Exit Codes#

• 0: No errors (warnings/infos only or clean)
• 1: One or more errors found
• 2: File not found or invalid input

Requirements#

• Python 3.8+
• No external dependencies (pure stdlib)