Files

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

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