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>
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
# Application Design: prerendering
|
||||
|
||||
Details: [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md), [component-dependency.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](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 |
|
||||
@@ -0,0 +1,67 @@
|
||||
# Component Dependencies: prerendering
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Vite["vite.config.ts"]
|
||||
Router["src/router.tsx"]
|
||||
Root["routes/__root.tsx"]
|
||||
Client["src/client.tsx"]
|
||||
Routes["Page routes and catch-all route"]
|
||||
Hydrated["useHydrated and server-safe hooks"]
|
||||
Display["Reveal, DeferredImage, NoScriptNav"]
|
||||
Extract["config/externalizeInlineScripts.ts"]
|
||||
Logic["config/inlineScripts.ts"]
|
||||
Output["dist/client"]
|
||||
Preview["config/previewServer.ts"]
|
||||
Headers["config/securityHeaders.ts"]
|
||||
ServerConfig["config/serverConfig.ts"]
|
||||
E2E["e2e browser tests and Lighthouse"]
|
||||
|
||||
Vite --> Router
|
||||
Router --> Root
|
||||
Client --> Router
|
||||
Root --> Routes
|
||||
Routes --> Hydrated
|
||||
Routes --> Display
|
||||
Display --> Hydrated
|
||||
Vite --> Output
|
||||
Extract --> Logic
|
||||
Extract --> Output
|
||||
Preview --> Output
|
||||
Preview --> Headers
|
||||
ServerConfig --> Headers
|
||||
E2E --> Preview
|
||||
|
||||
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef app fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef infra fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef check fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class Vite,Extract,Logic,Output build;
|
||||
class Router,Root,Client,Routes,Hydrated,Display app;
|
||||
class Preview,Headers,ServerConfig infra;
|
||||
class E2E check;
|
||||
```
|
||||
|
||||
Text alternative: the Vite config drives the router, root route and pages, which use hydration-safe hooks and display components; the post-build step rewrites the client output; the preview server serves that output with the shared headers for the browser tests and Lighthouse.
|
||||
|
||||
## Dependency matrix
|
||||
|
||||
| Component | Depends on | Used by | Communication |
|
||||
|---|---|---|---|
|
||||
| `tanstackStart` plugin | `src/router.tsx`, route tree | Build | Build time |
|
||||
| `__root.tsx` shell | `HeadContent`, `Scripts`, `ChakraProvider`, `theme.ts` | All pages | Render |
|
||||
| `useHydrated` | React | `NotFound`, search-dependent routes, display components | Hook |
|
||||
| `inlineScripts.ts` | None | Runner, tests | Pure function |
|
||||
| `externalizeInlineScripts.ts` | `inlineScripts.ts`, file system | `pnpm build` | Build time |
|
||||
| `previewServer.ts` | `securityHeaders.ts`, file system | Lighthouse, `e2e/` | HTTP |
|
||||
| `serverConfig.ts` | `securityHeaders.ts` | `deploy/` | Generated files |
|
||||
|
||||
## Unit boundaries
|
||||
|
||||
| Unit | Owns |
|
||||
|---|---|
|
||||
| 1 | Build and entry, hydration safety, script step, preview server, browser tests, test setup, CI output path |
|
||||
| 2 | `Reveal`, `DeferredImage`, `NoScriptNav`, no-JavaScript fallbacks, photo preload |
|
||||
| 3 | `serverConfig.ts`, `deploy/`, CI upload order, Lighthouse targets |
|
||||
|
||||
Units run in sequence, so shared files are not a merge concern.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Component Methods: prerendering
|
||||
|
||||
Signatures are the intended interfaces. Detailed rules follow in Functional Design.
|
||||
|
||||
## `config/inlineScripts.ts`
|
||||
|
||||
```ts
|
||||
type MovedScript = { fileName: string; body: string };
|
||||
type ExternalizeResult = { html: string; moved: MovedScript[] };
|
||||
|
||||
// Replaces each executable inline script with a reference to a file named
|
||||
// after its content hash; order and all other content stay as they are.
|
||||
export function externalizeInlineScripts(html: string): ExternalizeResult;
|
||||
|
||||
// Executable inline scripts still present; data blocks such as JSON-LD excluded.
|
||||
export function findExecutableInlineScripts(html: string): string[];
|
||||
```
|
||||
|
||||
## `config/externalizeInlineScripts.ts`
|
||||
|
||||
```ts
|
||||
// Rewrites all HTML under clientDir and writes moved scripts to clientDir/assets.
|
||||
// Exits non-zero when a page has no moved scripts or a violation remains.
|
||||
export function externalizeOutput(clientDir: string): void;
|
||||
```
|
||||
|
||||
## `config/previewServer.ts`
|
||||
|
||||
```ts
|
||||
// Maps a request path to a file following the nginx rules.
|
||||
export function resolveRequest(
|
||||
path: string,
|
||||
fileExists: (file: string) => boolean,
|
||||
): { file: string; status: 200 | 404 } | { redirect: string };
|
||||
|
||||
export function startPreviewServer(clientDir: string, port: number): Server;
|
||||
```
|
||||
|
||||
## `src/router.tsx`
|
||||
|
||||
```ts
|
||||
export function getRouter(): AnyRouter;
|
||||
```
|
||||
|
||||
## `src/hooks/useHydrated.ts`
|
||||
|
||||
```ts
|
||||
export default function useHydrated(): boolean;
|
||||
```
|
||||
|
||||
## `src/components/Reveal`
|
||||
|
||||
```ts
|
||||
// Props are unchanged, so the 21 call sites stay as they are.
|
||||
type RevealProps = BoxProps & { delay?: number };
|
||||
```
|
||||
|
||||
`useReveal<T>()` keeps returning `{ ref, visible }`. `visible` now starts as `true` and only becomes `false` when the element is below the viewport after hydration.
|
||||
|
||||
## `src/components/DeferredImage`
|
||||
|
||||
Props are unchanged. The rendered output gains a `<noscript>` image.
|
||||
|
||||
## `src/seo.ts`
|
||||
|
||||
```ts
|
||||
// Adds the preload link for a page's first photo to its head.
|
||||
export function preloadImage(src: string): HeadLink;
|
||||
```
|
||||
|
||||
## Route `head()`
|
||||
|
||||
Pages pass their first photo to `pageHead`, so the existing `pageHead(path)` helper stays the single source for head tags. The exact shape is settled in unit 2.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Components: prerendering
|
||||
|
||||
All paths are under `web/`. "New" and "changed" refer to master at c4c2f83.
|
||||
|
||||
## Build and entry (unit 1)
|
||||
|
||||
| Component | Status | Responsibility |
|
||||
|---|---|---|
|
||||
| `vite.config.ts` | Changed | Adds the `tanstackStart` plugin with prerendering; the plugin is left out under Vitest |
|
||||
| `src/router.tsx` | New | `getRouter()`: the router options now in `main.tsx` (scroll restoration, default error component) |
|
||||
| `src/routes/__root.tsx` | Changed | Renders the document through `shellComponent` (`html`, `HeadContent`, providers, `Scripts`); imports the fonts |
|
||||
| `src/client.tsx` | New | Browser entry: starts Sentry, then hydrates. Replaces `main.tsx` |
|
||||
| `src/main.tsx`, `index.html` | Removed | Start generates the document; fallback tags are no longer needed |
|
||||
| `config/inlineScripts.ts` | New | Pure logic: finds executable inline scripts in HTML and replaces them with file references |
|
||||
| `config/externalizeInlineScripts.ts` | New | Post-build runner: applies the logic to all HTML in the output, writes the files, fails the build on a violation |
|
||||
| `config/previewServer.ts` | New | Static server for Lighthouse and browser tests, following the nginx rules and using `securityHeaders` |
|
||||
| `e2e/` | New | Browser tests against the built output: hydration, CSP, content without JavaScript |
|
||||
| `src/test/renderApp.tsx` | Changed | Renders the app without the document shell in jsdom |
|
||||
|
||||
## Hydration safety (unit 1)
|
||||
|
||||
| Component | Status | Responsibility |
|
||||
|---|---|---|
|
||||
| `src/hooks/useHydrated.ts` | New | `false` during prerendering and the first browser render, then `true` |
|
||||
| `routes/index.tsx`, `routes/contact.tsx`, `routes/portfolio.tsx` | Changed | Search values take effect after hydration, through `useHydrated` |
|
||||
| `usePageLoaded`, `useInView` | Changed | Same first render on server and client |
|
||||
| `NavigationBar`, `useReveal`, `useHeroSlider`, `TestimonialCarousel`, `ContactSection` | Changed | Breakpoint and media query values start from a server-safe value; `useHeroSlider` also reads `document.hidden` safely |
|
||||
| `UmamiAnalytics` | Changed | Reads the hostname in its effect, not during render |
|
||||
| `Footer`, `ContactDetails`, `lib/contactChannels.ts`, `ContactFormGate`, `ContactForm` | Changed | E-mail address only after hydration (FR-PR-22); `Footer` also renders the year safely |
|
||||
| `src/routes/$.tsx` | New | Catch-all route rendering `NotFound`; source of `404.html` |
|
||||
| `NotFound` | Changed | Shows the shoot section buttons after hydration |
|
||||
|
||||
## Display (unit 2)
|
||||
|
||||
| Component | Status | Responsibility |
|
||||
|---|---|---|
|
||||
| `Reveal`, `useReveal` | Changed | Visible in the HTML; only content below the viewport at load is hidden for its fade-in |
|
||||
| `DeferredImage` | Changed | Real image for visitors without JavaScript; deferred loading with JavaScript stays |
|
||||
| `NoScriptNav` | New | Rendered inside `<noscript>`: a menu link, a close link and the CSS that shows `#mobile-nav` through `:target` and expands the shoot submenu |
|
||||
| `Hero`, `TestimonialCarousel`, `ContactSection` | Changed where needed | First slide, usable content and mailto route without JavaScript |
|
||||
| `seo.ts` and route `head()` | Changed | Preload link for the first photo per page |
|
||||
|
||||
## Hosting (unit 3)
|
||||
|
||||
| Component | Status | Responsibility |
|
||||
|---|---|---|
|
||||
| `config/serverConfig.ts`, `deploy/` | Changed | URL rules and real 404 on nginx and IIS |
|
||||
| `.gitea/workflows/continuous_integration.yaml` | Changed | Client output only; upload order for all HTML files. The output path itself changes in unit 1 |
|
||||
| `lighthouserc.cjs`, `lighthouserc.desktop.cjs` | Changed | Preview server, final targets |
|
||||
@@ -0,0 +1,48 @@
|
||||
# Services: prerendering
|
||||
|
||||
The site has no runtime services. The orchestration in this feature happens at build time and once in the browser.
|
||||
|
||||
## Build pipeline
|
||||
|
||||
`pnpm build` runs in this order:
|
||||
|
||||
1. `tsc`
|
||||
2. `vite build`: Start builds client and server, runs the server locally and prerenders each page to `dist/client`
|
||||
3. `node config/externalizeInlineScripts.ts`: moves inline scripts and guards the result
|
||||
|
||||
The server output in `dist/server` exists only during the build and is never deployed.
|
||||
|
||||
## Page load in the browser
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) Browser
|
||||
participant V as Visitor
|
||||
participant R as React
|
||||
end
|
||||
box rgba(99,179,237,0.4) Static host
|
||||
participant H as nginx or IIS
|
||||
end
|
||||
V->>H: Request page
|
||||
H-->>V: Complete HTML with styles
|
||||
V->>H: Request first photo through preload
|
||||
H-->>V: First photo
|
||||
V->>H: Request scripts at end of body
|
||||
H-->>V: Moved scripts and main bundle
|
||||
R->>R: Hydrate with the same first render as the HTML
|
||||
R->>R: Apply browser values such as search, breakpoints and fade-in
|
||||
```
|
||||
|
||||
Text alternative: the host returns complete HTML, the first photo is preloaded, scripts load at the end of the body, React hydrates with the same first render as the HTML, and only then applies values that exist in the browser.
|
||||
|
||||
## Pure functions and testable properties (PBT-01)
|
||||
|
||||
Confirmed per unit in Functional Design and Infrastructure Design.
|
||||
|
||||
| Function | Category | Property |
|
||||
|---|---|---|
|
||||
| `externalizeInlineScripts` | Invariant | Script order is preserved; all non-script content is unchanged |
|
||||
| `externalizeInlineScripts` | Round-trip | Putting each moved body back at its reference restores the original HTML, apart from the tag's attributes |
|
||||
| `externalizeInlineScripts` | Idempotence | Applying it twice gives the result of applying it once |
|
||||
| `externalizeInlineScripts`, `findExecutableInlineScripts` | Invariant | Data blocks stay inline; no executable inline script remains in the result |
|
||||
| `resolveRequest` | Invariant | Every path gives a file, a 404 or one redirect; a path never leaves the client directory |
|
||||
Reference in New Issue
Block a user