Functional design, NFR requirements, code generation plan and summary, and build-and-test instructions with results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
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_SEEDis 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
pnpm install --frozen-lockfile
--frozen-lockfileinstalls exactly whatpnpm-lock.yamlpins (SECURITY-10).postinstallrunschakra typegen, which generates the theme types (recipe variants such aslinksubtle) intonode_modules. Without it,tscfails on custom variants.
2. Build
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.htmlwith the fallback head (title, description, Open Graph, canonical)assets/with hashed JS, CSS, fonts and images; one chunk per routesitemap.xml, generated fromsrc/sitePages.ts, indexed pages onlyrobots.txt,og-image.jpg,logo.png,favicon.png(copied frompublic/)
- 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
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_modulesis 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
.tsextensions for that reason. - Fix: keep the
.tsextensions invite.config.ts,config/*and the modules they import.