Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/construction/build-and-test/build-instructions.md
T
SluijsensandClaude Opus 5.5 069c7cb7eb Adds AI-DLC construction docs for the front-end shell feature
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>
2026-10-18 17:05:03 +02:00

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.