# Build Instructions — frontend-shell ## Prerequisites - **Node.js** 24 (tested with v24.16.0) - **pnpm** 12 (tested with 12.11.2) - **Google Chrome**, only for `pnpm lighthouse` / `pnpm check` - **Environment variables**: none required. `FC_SEED` is optional (see unit-test-instructions.md). - **OS**: tested on Windows 11; nothing OS-specific in the build ## Build Steps All commands run in `web/`. ### 1. Install dependencies ```bash pnpm install --frozen-lockfile ``` - `--frozen-lockfile` installs exactly what `pnpm-lock.yaml` pins (SECURITY-10). - `postinstall` runs `chakra typegen`, which generates the theme types (recipe variants such as `link` `subtle`) into `node_modules`. Without it, `tsc` fails on custom variants. ### 2. Build ```bash pnpm build ``` This runs `tsc` (type check) and then `vite build`. ### 3. Verify the build - **Expected output**: `✓ built in …`, no TypeScript errors. - **Artifacts in `dist/`**: - `index.html` with the fallback head (title, description, Open Graph, canonical) - `assets/` with hashed JS, CSS, fonts and images; one chunk per route - `sitemap.xml`, generated from `src/sitePages.ts`, indexed pages only - `robots.txt`, `og-image.jpg`, `logo.png`, `favicon.png` (copied from `public/`) - **Accepted warning**: "Some chunks are larger than 500 kB". The main chunk is ~580 kB (≈170 kB gzip), mostly Chakra UI. It is tracked under performance (NFR-P-01 exception). ### 4. Run the built site locally ```bash pnpm preview # http://localhost:4173, with the production security headers ``` Measure performance against this, not against `pnpm dev`: the dev server is unbundled, unminified and loads devtools (measured 0.47 vs 0.82 on mobile). ## Troubleshooting ### `tsc`: `Type '"subtle"' is not assignable to …` - **Cause**: the Chakra typegen output in `node_modules` is missing (for example after a manual reinstall with scripts disabled). - **Fix**: `pnpm typegen`, then build again. ### `pnpm install` warns about the store location - **Cause**: the global pnpm store is on another drive than the project, so pnpm cannot hard-link from it. - **Fix**: none needed; pnpm uses a store on the project drive. Optionally set `storeDir`. ### Vite warns about imports without a file extension in the config - **Cause**: Vite 8's native config loader requires extensions. The config import chain uses `.ts` extensions for that reason. - **Fix**: keep the `.ts` extensions in `vite.config.ts`, `config/*` and the modules they import.