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>
7.9 KiB
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=gezinand/?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./404and/404.html: these technically exist as files. Infrastructure Design makes sure they do not appear as normal pages, and the page staysnoindexand 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 |