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>
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# 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.
|