4.6 KiB
4.6 KiB
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 (
packageManagerinweb/package.json), run fromweb/. Vite with TanStack Start (prerender), TypeScript (tscruns first). - Runtime: Node.js v24.16.0 (the version of the measurements and the local runs).
- Dependencies: installed from
web/pnpm-lock.yamlonly (pnpm install --frozen-lockfile). Thepostinstallhook runschakra typegen ./src/theme.ts. The feature added exact pins for@tanstack/react-start1.169.4 and@tanstack/react-router1.170.46, a pin forplaywright-core1.55.0, and azod@4override (^4.6.6) inpnpm-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 (seeunit-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 (seeperformance-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
nginxandlftpinstalled. The CI job installs both; the author's PC has neither, so those suites are skipped there.
Build Steps
1. Install Dependencies
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
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.tsmoves every inline executable script into/assets/inline-<hash>.jsand fails the build if an inline script, anon*=attribute or ajavascript: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.confandweb/deploy/iis/web.configcome fromweb/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 and404.html),sitemap.xml, and all assets including the moved scripts. This folder is the CI artifactdistand 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_modulesfrom another branch (this feature changedpackage.jsonand the lockfile). - Solution: run
pnpm install --frozen-lockfileagain. Do not change the lockfile in this stage; report the failure with its output.
Build Fails with Compilation Errors
- Cause:
tscerrors.src/routeTree.gen.tsis generated by the TanStack plugin. - Solution: read the first
error TSline. If it is inrouteTree.gen.ts, runpnpm exec vite buildonce to regenerate it, thenpnpm build. Do not hand-edit the generated file.
Build Fails in the Script Step
- Cause:
externalizeInlineScripts.tsfound an inline executable script, anon*=attribute or ajavascript: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 e2eruns against the build output. - Solution: run
pnpm buildfirst.