Files
SluijsensandClaude Opus 5.5 65c850e949 Adds the prerendering requirements, design and baseline
Records the requirements, execution plan, application design, the first unit's
functional design and code generation plan, and the baseline on master.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 17:41:12 +01:00

7.9 KiB

Application Design: prerendering

Details: components.md, component-methods.md, services.md, component-dependency.md.

Spike Evidence

Tested in a throwaway app outside the repository: @tanstack/react-start 1.169.4 and @tanstack/react-router 1.170.46 with Chakra, in Chrome, against a static test server with the production script-src. The app had three simple pages, so the real components are still untested.

Test Result
Inline scripts under the production CSP Blocked; page error; content disappears
Inline scripts moved to /assets Hydrates; button and client-side link work; no CSP violations
autoSubfolderIndex: false, served as /over-mij.html for /over-mij Status 200, no redirect, no errors
404 page rendered from a route giving status 404 Build fails: Start rejects a non-OK response
Separate /404 route, served for unknown URLs Status 404 and correct URL, but React hydration error #418
Start's SPA shell as the 404 page Rejected: index.html is not generated, and error #418 remains
Catch-all $ route, prerendered to 404.html, URL-dependent output after hydration Status 404, correct URL, no hydration error
/?pakket=gezin reading the search value in the first render Correct value, but hydration error #418
Same, with the value applied after hydration Correct value, no error

Decisions

# Decision Reason Rejected
D1 Prerender with Start, autoSubfolderIndex: false, all pages listed from sitePages.ts URLs stay without a slash; a page cannot be forgotten through crawling alone Subfolder output: gives redirects to a trailing slash
D2 A small Node step after vite build moves the scripts, without an HTML parser dependency Runs on Start's final output; pure logic is testable; the browser also ends a script at the first </script> Vite plugin hook: ordering against Start's prerender is less clear
D3 Moved files are named after their content hash in /assets Long caching is safe, and identical scripts share a file Fixed names: unsafe with long caching
D4 Keep the scripts at the end of the body, where Start puts them Content renders before they are fetched, which limits the cost of the extra requests Moving them to the head
D5 404 through a catch-all route rendering the existing NotFound The only tested option without a hydration error See the spike table
D6 One rule for hydration: the first browser render equals the HTML; browser-only values apply afterwards through useHydrated or server-safe defaults Prevents errors in Sentry, jumps and lost performance Suppressing warnings: hides the problem
D7 Reveal renders visible by default and hides only what is below the viewport after hydration The build cannot know the screen size. Content in view never flashes, and content is visible without JavaScript Hiding in HTML and revealing with JavaScript
D8 <noscript> image next to DeferredImage's image Keeps deferred loading, which protects the largest paint, and gives visitors without JavaScript the photo Loading all photos eagerly
D9 Mobile menu without JavaScript through <noscript> with :target CSS The JavaScript menu stays exactly as it is; style-src already allows this <details>: would change the tested menu behaviour and ARIA for everyone
D10 Own small preview server instead of vite preview Lighthouse and browser tests must see the real rules (status 404, .html mapping) and headers, with no Node server in production vite preview: SPA fallback, no real 404
D11 Browser tests with playwright-core, using the Chromium that the Lighthouse job already installs Hydration and CSP only show in a real browser jsdom: runs neither the CSP nor real hydration
D12 The Start plugin stays out of Vitest, and renderApp renders without the document shell The large existing test suite keeps testing components; <html> cannot render inside a test container Rewriting the test setup
D13 Sentry starts from a custom src/client.tsx, before hydration Keeps catching errors from the start; it must not run during prerendering Starting in an effect: misses early errors

Consequences the Owner Should Know

  • /portfolio?shoot=gezin and /?pakket=gezin: the first paint shows the page without the filter or chosen package, and the filter or package applies right after hydration. On the portfolio, the visitor can briefly see all photos before the filter applies. This follows from one HTML file per page; the alternative would be separate pages per filter, which changes the URLs.
  • /404 and /404.html: these technically exist as files. Infrastructure Design makes sure they do not appear as normal pages, and the page stays noindex and out of the sitemap.
  • The 404 buttons under /soorten-fotoshoots/ appear right after hydration, and are missing without JavaScript. The page still has the normal menu links.
  • The IIS rules can only be tested in production, as the test environment runs nginx. Infrastructure Design covers how to limit that risk, including whether the webhost allows the required setting.

Open Points for Construction

Point Where settled
Custom client entry src/client.tsx: not tested in the spike, and how Start supports it is still to be confirmed Unit 1
JSON-LD through StructuredData under the CSP Unit 1 browser test
lazy() contact form and code-split routes during prerendering Unit 1
Sitemap plugin with Start's separate client and server builds Unit 1
Main bundle and Lighthouse on the real app Unit 1 decision gate
Flicker with Emotion styles on real pages Unit 1
Trailing slash and /404 rules; webhost limits for 404 handling Unit 3 Infrastructure Design

Requirement Coverage

Requirements Unit Design
FR-PR-01 to 04, 19, 20 1 D1 to D4
FR-PR-05 to 08, 22 1 D6, D13
FR-PR-09, 10 2 D7
FR-PR-11 to 13 2 D7 to D9
FR-PR-14, 15 1 (route), 3 (servers) D5, D10
FR-PR-16 to 18 3 D1, Infrastructure Design
FR-PR-21 2 preloadImage
NFR-PR-P-01, P-02, S-01 3 Final Lighthouse targets
NFR-PR-P-03, P-04 1 Decision gate, D4
NFR-PR-S-02, SEC-01, Q-03 1 D10, D11
NFR-PR-SEC-02 to 04, Q-01, Q-02, Q-04, Q-05 1, carried through 2 and 3 D2, D12

Extension Compliance

Security Baseline

Rule Status Note
SECURITY-03 Compliant Sentry stays the error logging; no new logging surface
SECURITY-04 Compliant Headers unchanged; style-src 'unsafe-inline' remains, already documented in securityHeaders.ts for Chakra and Emotion
SECURITY-09 Compliant Server build not deployed; generic error pages; directory handling covered in Infrastructure Design
SECURITY-10 Compliant New packages go through the lockfile and audit:deps; seroval patch kept. The repository generates no SBOM, as with earlier features
SECURITY-11 Compliant Misuse case: a path in the preview server escaping the client directory is a tested property. No public endpoints are added
SECURITY-13 Compliant No external scripts added; serialized data is public page data and read only from same-origin files
SECURITY-15 Compliant Build fails closed on script violations; the global error page stays
SECURITY-01, 02, 05, 06, 07, 08, 12, 14 N/A No data stores, intermediaries, APIs, access policies, network rules, accounts or security events in this feature

Property-Based Testing

Rule Status Note
PBT-01 Compliant Candidates in services.md; confirmed per unit
PBT-09 Compliant fast-check is already a dependency and runs in Vitest
PBT-02 to 08, 10 N/A at this stage Enforced in Code Generation and Build and Test