> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel + Vite 8 + Node — build guardrails

> Purpose: Avoid repeat production build failures (Vercel, CI, local) when toolchain assumptions drift.

**Purpose:** Avoid repeat production build failures (Vercel, CI, local) when toolchain assumptions drift.

**Last updated:** 2026-04-10

## Node.js version

* **`package.json` `engines.node`** is set to **`>=22 <25`** so that:
  * **`@julr/vite-plugin-validate-env`** (requires Node `>=22`) installs without `EBADENGINE` warnings.
  * Local, GitHub Actions, and Vercel use a consistent baseline.
* **Vercel:** Node version is controlled via **`package.json` `engines.node`** (highest priority; overrides Project Settings if valid) and via **Project Settings → Build & Development → Node.js Version** (fallback). The `build.env.NODE_VERSION` field in `vercel.json` is ineffective for runtime selection and should not be used. Set Project Settings → General → Node.js Version to **22.x** to align with `engines.node`. If the dashboard is set to a different major version while `engines` pins another, Vercel logs a warning and follows `engines` — keeping them aligned removes noise.

**Preflight (optional):**

```bash theme={null}
npm run verify:node-for-build
```

## Vite 8 + Rolldown

* **Do not use `vite-plugin-remove-console` with the current Vite 8 + Rolldown pipeline.** It has caused transform-time crashes (e.g. `TypeError: ...find is not a function`) on valid TSX.
* **Production console stripping** is handled by **`build.minify: 'esbuild'`** and root **`esbuild.drop: ['console', 'debugger']`** when `mode === 'production'`. This applies to client bundles only (not arbitrary Node scripts in `vite.config.ts` hooks).
* **Chunking** uses **`build.rolldownOptions.output.codeSplitting.groups`**, not Rollup’s deprecated `manualChunks` (Rolldown rejects unknown `manualChunks`).

## PWA / Workbox (`vite-plugin-pwa`)

* **`workbox.globPatterns`** should match emitted artifacts under `dist/` (e.g. `assets/**/*.{js,css}`, HTML, static extensions). Empty-glob warnings often mean the main app bundle failed to emit before the PWA step — fix the primary build error first.

## Vercel MCP verification

After pushing to the connected Git branch, confirm the latest deployment and build logs:

* `list_deployments` → `get_deployment` / `get_deployment_build_logs` for the failing or latest `dpl_*`.
* `get_runtime_logs` for production/preview **after** a successful deploy (build failures produce no runtime logs).

## Related

* [CI\_PIPELINE.md](./CI_PIPELINE.md) — local parity with GitHub Actions
* [VERCEL\_BUILD\_IMPROVEMENT\_PLAN.md](./VERCEL_BUILD_IMPROVEMENT_PLAN.md) — build workflow context
* [PERFORMANCE\_OPTIMIZATION\_GUIDE.md](./PERFORMANCE_OPTIMIZATION_GUIDE.md) — Rolldown chunk groups vs `manualChunks`

## Bun lockfile

If you use Bun, run `bun install` after `package.json` dependency changes so `bun.lock` stays in sync with npm removals (e.g. removed devDependencies).