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:

bash

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#

bash

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

bash

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#

bash

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#

bash

python3 scripts/vite_config_validator.py suggest vite.config.json
python3 scripts/vite_config_validator.py suggest vite.config.json --format json

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 (25)#

Structure (5)#

RuleSeverityDescriptionS1errorFile not found or unreadableS2errorEmpty config fileS3errorInvalid JSON syntaxS4warningUnknown top-level keys (not in Vite's valid config options)S5infodefineConfig() wrapper hint (cannot verify in JSON export)

Build (5)#

RuleSeverityDescriptionB1infoMissing build.outDir (defaults to 'dist')B2errorInvalid build.target valueB3errorInvalid build.minify value (not boolean, 'terser', or 'esbuild')B4warningbuild.sourcemap set to 'hidden' in development modeB5warningDeprecated Rollup plugins (rollup-plugin-* vs @rollup/plugin-*)

Server (4)#

RuleSeverityDescriptionV1error/warningserver.port out of valid range or privileged portV2warningserver.host set to true/0.0.0.0 (security: exposes to network)V3warningserver.proxy with invalid target URLsV4warningserver.https without cert/key paths

Resolve (3)#

RuleSeverityDescriptionR1warningresolve.alias with absolute paths (portability risk)R2infoMissing resolve.extensions for TypeScript projectsR3warningresolve.dedupe with empty array

CSS (3)#

RuleSeverityDescriptionC1infocss.preprocessorOptions without corresponding preprocessor dependency hintC2warningcss.modules with invalid or unknown optionsC3warningcss.postcss pointing to non-existent file

Plugins (2)#

RuleSeverityDescriptionP1infoEmpty plugins arrayP2warningDeprecated Vite plugin names

Best Practices (3)#

RuleSeverityDescriptionX1infoNo mode set in configX2infoMissing base path for non-root deploymentsX3warningbuild.chunkSizeWarningLimit too high (>2000 kB)

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

text

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