Metadata
- name
- vite-config-validator
- description
- Validate Vite configuration files (JSON-exported) for structural correctness, build settings, server security, resolve/CSS hygiene, plugin deprecations, and best practices. Use when auditing Vite projects, enforcing config standards in CI, or reviewing vite.config.ts changes.
Vite Config Validator
Validate Vite configuration files exported as JSON for structural correctness, build settings, server configuration, resolve/CSS options, plugin hygiene, and best practices. Uses pure Python 3 stdlib (json, argparse, re, os, sys) -- no external dependencies.
Since Vite configs are JS/TS (vite.config.ts), the validator works with JSON-exported snapshots. Export your config first:
node -e "import('./vite.config.ts').then(m => console.log(JSON.stringify(m.default)))" > vite.config.json
Then validate the JSON output.
Commands
validate -- Full validation with all rules
python3 scripts/vite_config_validator.py validate vite.config.json
python3 scripts/vite_config_validator.py validate vite.config.json --strict
python3 scripts/vite_config_validator.py validate vite.config.json --format json
check -- Quick check (errors and warnings only)
python3 scripts/vite_config_validator.py check vite.config.json
python3 scripts/vite_config_validator.py check vite.config.json --format summary
explain -- Show all rules with descriptions
python3 scripts/vite_config_validator.py explain vite.config.json
python3 scripts/vite_config_validator.py explain vite.config.json --format json
suggest -- Run validation and propose fixes
python3 scripts/vite_config_validator.py suggest vite.config.json
python3 scripts/vite_config_validator.py suggest vite.config.json --format json
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 (25)
Structure (5)
| Rule |
Severity |
Description |
| S1 |
error |
File not found or unreadable |
| S2 |
error |
Empty config file |
| S3 |
error |
Invalid JSON syntax |
| S4 |
warning |
Unknown top-level keys (not in Vite's valid config options) |
| S5 |
info |
defineConfig() wrapper hint (cannot verify in JSON export) |
Build (5)
| Rule |
Severity |
Description |
| B1 |
info |
Missing build.outDir (defaults to 'dist') |
| B2 |
error |
Invalid build.target value |
| B3 |
error |
Invalid build.minify value (not boolean, 'terser', or 'esbuild') |
| B4 |
warning |
build.sourcemap set to 'hidden' in development mode |
| B5 |
warning |
Deprecated Rollup plugins (rollup-plugin-* vs @rollup/plugin-*) |
Server (4)
| Rule |
Severity |
Description |
| V1 |
error/warning |
server.port out of valid range or privileged port |
| V2 |
warning |
server.host set to true/0.0.0.0 (security: exposes to network) |
| V3 |
warning |
server.proxy with invalid target URLs |
| V4 |
warning |
server.https without cert/key paths |
Resolve (3)
| Rule |
Severity |
Description |
| R1 |
warning |
resolve.alias with absolute paths (portability risk) |
| R2 |
info |
Missing resolve.extensions for TypeScript projects |
| R3 |
warning |
resolve.dedupe with empty array |
CSS (3)
| Rule |
Severity |
Description |
| C1 |
info |
css.preprocessorOptions without corresponding preprocessor dependency hint |
| C2 |
warning |
css.modules with invalid or unknown options |
| C3 |
warning |
css.postcss pointing to non-existent file |
Plugins (2)
| Rule |
Severity |
Description |
| P1 |
info |
Empty plugins array |
| P2 |
warning |
Deprecated Vite plugin names |
Best Practices (3)
| Rule |
Severity |
Description |
| X1 |
info |
No mode set in config |
| X2 |
info |
Missing base path for non-root deployments |
| X3 |
warning |
build.chunkSizeWarningLimit too high (>2000 kB) |
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
# GitHub Actions
- name: Validate Vite config
run: |
node -e "import('./vite.config.ts').then(m => console.log(JSON.stringify(m.default)))" > /tmp/vite.config.json
python3 scripts/vite_config_validator.py validate /tmp/vite.config.json --strict --format json
Example Output
vite.config validate -- vite.config.json
=========================================
[ERROR ] B2: Invalid build.target value: 'ie11'
Valid targets: 'modules', 'esnext', 'es20XX', or browser versions like 'chrome87', 'firefox78', 'safari13'.
[WARNING] V2: server.host exposes dev server to all network interfaces
Setting host to true or '0.0.0.0' makes the dev server accessible from any device on the network. Use 'localhost' or '127.0.0.1' for local-only.
[WARNING] X3: build.chunkSizeWarningLimit is very high (5000 kB)
A limit above 2000 kB effectively silences chunk size warnings. Large chunks hurt load performance. Consider code splitting instead of raising the limit. Default is 500 kB.
[INFO ] S5: JSON export cannot verify defineConfig() wrapper
Wrap your config with defineConfig() in vite.config.ts for type safety and IDE autocompletion: export default defineConfig({ ... })
[INFO ] X1: No mode set in config
Vite defaults to 'development' for serve and 'production' for build. Set mode explicitly if you need environment-specific behavior in the config itself.
Result: INVALID
Summary: 1 error(s), 2 warning(s), 2 info
