vite-spa-patterns

When to trigger

• Implementing a spec that names a Vite + React SPA change.
• Adding or modifying a route in the SPA (auth-gated by default).
• Authoring build-config changes in vite.config.ts.
• Env-handling decisions: which variables need VITE_ prefix; distinguishing public vs. server-only values.
• Code-splitting boundary decisions (lazy-loading a new feature module).
• Debugging a Vite build issue — chunk size warnings, tree-shaking problems, env-var not injected.

Procedure

1. Determine route type: default is auth-gated. A public route is an exception that requires an explicit decision recorded in the spec. If in doubt, gate it.

2. Place the route file per the routing-library convention the project uses. Follow the existing router setup in the package's src/router/ (or equivalent) before introducing a new pattern.

3. Lazy-load the route via dynamic import to enforce code-splitting boundary: const MyPage = lazy(() => import('./pages/MyPage')) wrapped in <Suspense fallback={<LoadingSpinner />}>. Every route is lazy-loaded unless it is the top-level app shell.

4. Env access via import.meta.env.VITE_* (never process.env — Vite does not expose process.env by default). Variables without the VITE_ prefix are only available at build time in vite.config.ts; they are NOT injected into the client bundle. Secret values (API keys, tokens) must NEVER use the VITE_ prefix — they become part of the public bundle.

5. Build-config changes go in vite.config.ts at the package root. Document every config addition with a one-line comment explaining why. Do not add plugins speculatively.

6. Build verification + lint + typecheck: confirm the package builds cleanly with {{ profile.static_validation.build }} from the project root, scoped to the target package, and run lint + typecheck before marking the PR ready.

Dependency installation

Default command for population on a fresh worktree or after a git pull that includes a lockfile change: npm ci — lockfile-respecting, deterministic install. Run from the project root. This is the form CI workflows and Dockerfiles use. The bare npm install form is acceptable only when the lockfile is known-stale or for the initial devcontainer bootstrap; for the per-PR verifier flow, npm ci is the default.