monorepo-template / frontend

---
description: "Vite 8 config for front-* SPAs - Rolldown/Oxc, plugin order, monorepo fs, env guards."
alwaysApply: false
globs: apps/front-*/vite.config.ts
---

## Config shape

- `defineConfig(({ command, mode }) => …)` - compare `command === "build"` / `command === "serve"` explicitly.
- `appDir` from `import.meta.url`, not `process.cwd()`. Config-time env: `loadEnv(mode, appDir, "VITE_")` - `.env*` is not in `process.env` during config evaluation.
- Small build-only plugins inline; extract only when shared across `front-*` apps. TS bundling issues: `vite --configLoader runner`.

## Vite 8 (Rolldown + Oxc)

- `build.rolldownOptions` / `optimizeDeps.rolldownOptions` - not deprecated `rollupOptions` / `esbuildOptions`. `build.minify: "oxc"`. `build.commonjsOptions` is a no-op.
- `manualChunks` (function) works but is deprecated - preserve existing splits when editing; use `codeSplitting` for refactors.

## Plugins (order matters)

`devtools` → `tanstackRouter` (**before** `react`) → `react({ compiler: true })` (native Rust React Compiler via optional peer `oxc-transform-react`; no Babel pass) → `tailwindcss` → `cloudflare` → build-only (`apply: "build"`) → conditional via spread. Falsy plugins are skipped. Compiler on → less manual memoization ([react.mdc](react.mdc)). Do not configure `auxiliaryWorkers` on `front-*` to embed `worker-api` or other backends - HTTP-only SPA boundary.

## DevTools

- `DevTools()` (embedded plugin) and the top-level `devtools` config key are alternatives, not complements - enabling the key registers a *second* DevTools instance on serve and calls `start()` on build. Stay on the plugin.
- Keep `build.rolldownOptions.devtools` set explicitly. `@vitejs/devtools` only seeds it from `DevToolsBuildIntegration`, which Vite registers when the top-level `devtools` key is enabled; that key is absent here, so without the explicit flag no build writes `node_modules/.rolldown` and the Rolldown dock stays empty (`RDDT0001`). Populate it with one `build`.
- `embeddedVisibility: "passive"` keeps Vite's floating dock clear of TanStack's; **Shift+Alt+D** reveals it.
- The `devframe auth code` banner is the client auth handshake, not an error. `clientAuthTokens` is readable only from the top-level key, so it stays un-pre-approved; never set `clientAuth: false` - it exposes the dev server and filesystem to any browser that can reach the port.
- `@vitest/ui` stays a **root** devDependency: `@vitejs/devtools-vitest` probes for it at the pnpm workspace root, so an app-local install fails the Vitest dock with `VTDT0001` ([knip.mdc](../quality/knip.mdc)).

## Monorepo

- `server.fs.allow: [repoRoot]` (`path.resolve(appDir, "../..")`) for `@repo/*`; leave `server.fs.strict` at its default (`true`).
- In-app absolute imports use package.json `"imports"` (`#/*` → `./src/*`); Vite resolves them natively - do not add `resolve.alias` for the same map.

## Dev server

- Ports per app in [ports.mdc](../backend/ports.mdc) (frontends **5170–5199**); set `server.port` / `preview.port` + `strictPort: true` in each app's config.
- `server.warmup.clientFiles` for hot entry files only. Keep `server.forwardConsole` (or `{ unhandledErrors: true, logLevels: ["warn", "error"] }`) for agentic dev.

## Build, env, deps

- Leave `build.target` unset (Vite 8 default `baseline-widely-available`). `sourcemap`: inline (development mode) / `hidden` (production - maps kept for symbolication, excluded from upload via `*.map` in generated `dist/.assetsignore`). `reportCompressedSize: false`; leave `cssCodeSplit`, `assetsInlineLimit`, and `chunkSizeWarningLimit` at their defaults. Leave `modulePreload.polyfill` at its Vite default `true` unless you intentionally drop older-browser preload support.
- Chunk vendors: react, tanstack-router, tanstack-query, workspace packages, catch-all `node_modules`. HTML `Cache-Control: no-cache` via generated `_headers`.
- Handle `vite:preloadError` in the client entry: reload once per session (sessionStorage guard) so returning users recover from stale-chunk loads after deploys.
- Only `VITE_*` in client bundle - no secrets. Fail production `build` on missing/placeholder required vars; skip under static analysis (`knip`). Generate `dist/_headers` + append to `dist/.assetsignore` in a build plugin - never hand-edit ([guardrails.mdc](../core/guardrails.mdc)). Deploy in `wrangler.jsonc`.
- `optimizeDeps.entries` + `include` for heavy deps - dev pre-bundler only, not production bundle size.

## Verification

`pnpm run ci` → `pnpm --filter <front-app> run build`. Analyze: `ANALYZE=true vite build` when the app exposes an `analyze` script.