magnus919_agent-skills/react/references/vite-diagnostics.md

Vite Diagnostics And Release Checks

Environment values

Vite substitutes client-exposed variables at build time. Only variables with the configured public prefix (commonly VITE_) should be read by browser code. Treat every such value as public: it is not a secret merely because it lives in .env. Keep credentials and server-only configuration outside the client bundle. Check .env.example, Vite config, deployment configuration, and the actual built assets for accidental exposure.

Vite loads mode-specific files with a defined precedence. Confirm the intended mode (development, production, or a custom mode) and do not assume a local .env matches CI. When diagnosing a value, inspect its name and source without printing its value. Re-run the build after changing env configuration because substitution is compile-time.

Build and asset paths

Inspect base in vite.config.* when the app is served below /. A wrong base usually appears as 404s for module, CSS, or asset URLs after deployment even though the root-local dev server works. Validate the generated HTML and asset references against the real deployment path. For SPA history fallback, confirm the host serves the app entry point for non-root routes; Vite does not configure that server rule for every deployment target.

Dependency and output checks

Use the project's package manager lockfile and scripts. Check that react and react-dom versions are compatible and that duplicate React copies are not being pulled into the bundle, which can produce invalid hook call errors. Do not blindly delete lockfiles or upgrade dependencies while diagnosing.

For release verification, run the existing typecheck/lint/test commands before vite build, inspect warnings, and use a preview server for a smoke check at the deployed base path. Keep source maps and reports out of user-facing output unless the project intentionally publishes them.

Safe diagnostic sequence

1. Record the package manager and available scripts from package.json.
2. Identify the active mode and public-prefix configuration without exposing values.
3. Inspect base, route fallback, and generated asset URLs.
4. Check lockfile consistency and React package version alignment.
5. Run the narrowest reproducible check, then the production build.
6. Confirm the browser flow with playwright when route, asset, or navigation behavior is involved.
7. Ask frontend-engineering for broader performance/component strategy and web-accessibility for a dedicated accessibility audit.