Files

64 lines
4.6 KiB
Markdown

# Build Instructions
Feature: prerendering (branch `feature/prerendering`, worktree `AndreaSlopFotografie-prerendering`).
Verified at HEAD `39dc456`. Only documents changed since `2006fa0`, the commit CI run 599 built (`git diff --stat 2006fa0 HEAD` lists `aidlc-state.md` and `audit.md` only). No build was run in this stage; the build facts come from CI run 599, the test deployment (run 598) and the code summaries.
## Prerequisites
- **Build Tool**: pnpm 12.11.2 (`packageManager` in `web/package.json`), run from `web/`. Vite with TanStack Start (prerender), TypeScript (`tsc` runs first).
- **Runtime**: Node.js v24.16.0 (the version of the measurements and the local runs).
- **Dependencies**: installed from `web/pnpm-lock.yaml` only (`pnpm install --frozen-lockfile`). The `postinstall` hook runs `chakra typegen ./src/theme.ts`. The feature added exact pins for `@tanstack/react-start` 1.169.4 and `@tanstack/react-router` 1.170.46, a pin for `playwright-core` 1.55.0, and a `zod@4` override (`^4.6.6`) in `pnpm-workspace.yaml` (unit 1 code summary, deviations 1 and 2).
- **Environment Variables**:
- `VITE_RELEASE`: set by CI to the commit SHA for Sentry. Not needed locally.
- `FC_SEED=<seed>`: replays a fast-check run (see `unit-test-instructions.md`).
- `CI=true`: makes a missing nginx fail the browser tests instead of skipping the nginx suites (BR-HST-24).
- `LIGHTHOUSE_PERFORMANCE=warn`, `LIGHTHOUSE_CHROME_FLAGS`: Lighthouse only (see `performance-test-instructions.md`).
- **System Requirements**: Windows 11 with Git Bash, or the Ubuntu CI container. The browser tests need Chromium (Playwright 1.55.0). The nginx and lftp suites need `nginx` and `lftp` installed. The CI job installs both; the author's PC has neither, so those suites are skipped there.
## Build Steps
### 1. Install Dependencies
```bash
cd web
pnpm install --frozen-lockfile
```
Expected: lockfile up to date, exit 0. In CI run 599 the install also printed `Lockfile passes supply-chain policies (910 entries)`.
### 2. Configure Environment
No configuration is needed for a local build. Do not create `.env` files.
### 3. Build All Units
```bash
cd web
pnpm build
```
`pnpm build` is `tsc && vite build && node config/externalizeInlineScripts.ts`. The three steps cover all three units together:
- Unit 1 (start migration): Vite builds a client and a server environment and prerenders one HTML file per page.
- Unit 1 (script step): `externalizeInlineScripts.ts` moves every inline executable script into `/assets/inline-<hash>.js` and fails the build if an inline script, an `on*=` attribute or a `javascript:` link remains.
- Units 2 and 3 are code and generated text inside the same build (no extra build step). The generated server files `web/deploy/nginx/andreaslop-test.conf` and `web/deploy/iis/web.config` come from `web/config/serverConfig.ts`; a unit test checks that the committed files equal the generator output.
### 4. Verify Build Success
- **Expected Output**: exit 0. At its Step 31 unit 1 reported "12 pages, 16 scripts moved (28 files written), no violations".
- **Build Artifacts** (gitignored):
- `web/dist/client/`: 12 HTML files (11 pages and `404.html`), `sitemap.xml`, and all assets including the moved scripts. This folder is the CI artifact `dist` and is what gets deployed.
- `web/dist/server/`: a sibling folder, not deployed.
- **Main bundle** (measured on the test server after run 598): 547,302 bytes raw, 155,603 bytes over the wire with gzip.
- **Common Warnings**: Vite's chunk-size warning (main bundle above 500 kB), as on master. Accepted.
## Troubleshooting
### Build Fails with Dependency Errors
- **Cause**: lockfile out of date, or `node_modules` from another branch (this feature changed `package.json` and the lockfile).
- **Solution**: run `pnpm install --frozen-lockfile` again. Do not change the lockfile in this stage; report the failure with its output.
### Build Fails with Compilation Errors
- **Cause**: `tsc` errors. `src/routeTree.gen.ts` is generated by the TanStack plugin.
- **Solution**: read the first `error TS` line. If it is in `routeTree.gen.ts`, run `pnpm exec vite build` once to regenerate it, then `pnpm build`. Do not hand-edit the generated file.
### Build Fails in the Script Step
- **Cause**: `externalizeInlineScripts.ts` found an inline executable script, an `on*=` attribute or a `javascript:` link in a prerendered page.
- **Solution**: the error names the file. Remove the inline code from the component. The CSP (`script-src 'self'` plus Umami) must not be loosened.
### Browser Tests Cannot Find `dist/client`
- **Cause**: `pnpm e2e` runs against the build output.
- **Solution**: run `pnpm build` first.