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

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_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

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

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

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.