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 |
|
||||
@@ -0,0 +1,23 @@
|
||||
# Application Design Plan: prerendering
|
||||
|
||||
Depth: standard. No question file was created: each open choice was settled by testing it in a spike or is purely technical, and the owner's decisions are in requirements.md. The design states its decisions and the consequences the owner should know. Business rules follow in Functional Design (units 1 and 2) and Infrastructure Design (unit 3).
|
||||
|
||||
## Plan
|
||||
|
||||
- [x] Analyse context
|
||||
- [x] Read requirements.md, execution-plan.md and the shared reverse-engineering artifacts
|
||||
- [x] Read in code: `main.tsx`, `__root.tsx`, `vite.config.ts`, `index.html`, `serverConfig.ts`, `securityHeaders.ts`, `lighthouserc.cjs`, the CI workflow, `Reveal`, `useReveal`, `useInView`, `DeferredImage`, `NavigationBar`, `MobileNav`, `NotFound`, `renderApp`
|
||||
- [x] Test the open technical choices in the spike
|
||||
- [x] Hydration under the production `script-src`, with inline and with moved scripts
|
||||
- [x] URLs without a trailing slash through `autoSubfolderIndex: false`
|
||||
- [x] Three ways to build the 404 page
|
||||
- [x] Search parameters during hydration
|
||||
- [x] Generate `components.md`
|
||||
- [x] Generate `component-methods.md`
|
||||
- [x] Generate `services.md`
|
||||
- [x] Generate `component-dependency.md`
|
||||
- [x] Generate `application-design.md`
|
||||
- [x] Validate design completeness and consistency
|
||||
- [x] Every FR-PR and NFR-PR item has a home in a unit
|
||||
- [x] Mermaid diagrams use `classDef` with `color:#000`, safe node ids and a text alternative
|
||||
- [x] Security Baseline and PBT compliance summarised; no blocking findings
|
||||
@@ -0,0 +1,171 @@
|
||||
# Execution Plan
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Transformation Scope
|
||||
- **Transformation Type**: Architectural, within one package (`web/`): from a client-rendered SPA to statically prerendered pages with hydration
|
||||
- **Primary Changes**: TanStack Start replaces the plain Vite entry; a post-build step moves inline scripts to files; `Reveal` and other display components work from prerendered HTML; nginx, IIS and CI handle the new output
|
||||
- **Related Components**: `vite.config.ts`, `main.tsx`, `index.html`, `routes/__root.tsx`, `AppShell`, `NavigationBar`/`MobileNav`, `Reveal`/`useReveal`, `DeferredImage`, `NotFound`, `seo.ts`, `config/serverConfig.ts`, `deploy/`, `lighthouserc*.cjs`, the CI workflow, the test setup
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes. Faster first paint, a changed fade-in at the top of pages, a mobile menu that works without JavaScript, a real 404
|
||||
- **Structural changes**: Yes. New app entry and root document, new build output, a new post-build step
|
||||
- **Data model changes**: No
|
||||
- **API changes**: No
|
||||
- **NFR impact**: Yes. Performance and SEO are the goal; the CSP must stay unchanged; the main bundle may grow
|
||||
|
||||
### Component Relationships
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start["TanStack Start build"]
|
||||
Entry["App entry and root document"]
|
||||
Pages["Routes and shared components"]
|
||||
Extract["Post-build script step"]
|
||||
Config["serverConfig and deploy files"]
|
||||
CI["CI workflow and Lighthouse"]
|
||||
Hosts["nginx and IIS"]
|
||||
Start --> Entry
|
||||
Entry --> Pages
|
||||
Start --> Extract
|
||||
Extract --> CI
|
||||
Config --> Hosts
|
||||
CI --> Hosts
|
||||
classDef core 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;
|
||||
class Start,Extract core;
|
||||
class Entry,Pages app;
|
||||
class Config,CI,Hosts infra;
|
||||
```
|
||||
|
||||
Text alternative: the Start build drives the app entry and pages and feeds the post-build step; its output goes through CI to nginx and IIS, which are configured from serverConfig.
|
||||
|
||||
| Component | Change type | Reason | Priority |
|
||||
|---|---|---|---|
|
||||
| Build, entry, root route | Major | Framework change | Critical |
|
||||
| Post-build script step (new) | Major | Keep the CSP unchanged | Critical |
|
||||
| `Reveal`, `DeferredImage`, `MobileNav`, breakpoint-dependent components | Minor to major | Prerendered HTML and working without JavaScript | Important |
|
||||
| `serverConfig.ts`, `deploy/` | Minor | URLs and real 404 | Critical |
|
||||
| CI workflow, Lighthouse configuration | Minor | New output path, targets | Critical |
|
||||
| Test setup | Minor | Framework change | Important |
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk Level**: High. System-wide change with unknowns; the spike covered two simple pages only
|
||||
- **Rollback Complexity**: Moderate. All work is on one branch, and the deployed result is static, so an earlier release can be put back
|
||||
- **Testing Complexity**: Complex. Hydration, CSP and no-JavaScript behaviour need a real browser against the built output on two server types
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["User Request"])
|
||||
|
||||
subgraph INCEPTION["🔵 INCEPTION PHASE"]
|
||||
WD["Workspace Detection<br/><b>COMPLETED</b>"]
|
||||
RE["Reverse Engineering<br/><b>SKIP</b>"]
|
||||
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
|
||||
US["User Stories<br/><b>SKIP</b>"]
|
||||
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
|
||||
AD["Application Design<br/><b>EXECUTE</b>"]
|
||||
UG["Units Generation<br/><b>SKIP</b>"]
|
||||
end
|
||||
|
||||
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
|
||||
FD["Functional Design<br/><b>EXECUTE, units 1 and 2</b>"]
|
||||
NFRA["NFR Requirements<br/><b>SKIP</b>"]
|
||||
NFRD["NFR Design<br/><b>SKIP</b>"]
|
||||
ID["Infrastructure Design<br/><b>EXECUTE, unit 3</b>"]
|
||||
CG["Code Generation<br/><b>EXECUTE</b>"]
|
||||
BT["Build and Test<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
Start --> WD
|
||||
WD --> RA
|
||||
RA --> WP
|
||||
WP --> AD
|
||||
AD --> FD
|
||||
FD --> ID
|
||||
ID --> CG
|
||||
CG --> BT
|
||||
BT --> End(["Complete"])
|
||||
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
|
||||
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
|
||||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
|
||||
linkStyle default stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
Text alternative: after Workflow Planning come Application Design, Functional Design (units 1 and 2), Infrastructure Design (unit 3), Code Generation and Build and Test; Reverse Engineering, User Stories, Units Generation and both NFR stages are skipped.
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### 🔵 INCEPTION PHASE
|
||||
- [x] Workspace Detection (COMPLETED)
|
||||
- [x] Reverse Engineering (SKIPPED)
|
||||
- **Rationale**: Shared artifacts exist; team agreement is no full refresh per feature
|
||||
- [x] Requirements Analysis (COMPLETED)
|
||||
- [x] User Stories (SKIPPED)
|
||||
- **Rationale**: One visitor type; the requirements are concrete and testable
|
||||
- [x] Execution Plan (IN PROGRESS)
|
||||
- [ ] Application Design - EXECUTE
|
||||
- **Rationale**: New entry, root document and post-build step; component responsibilities and open technical choices need settling before code
|
||||
- [ ] Units Planning / Units Generation - SKIP
|
||||
- **Rationale**: The three units below follow from the dependencies and are fixed in this plan
|
||||
|
||||
### 🟢 CONSTRUCTION PHASE
|
||||
- [ ] Functional Design - EXECUTE for units 1 and 2, SKIP for unit 3
|
||||
- **Rationale**: Script extraction rules and fade-in, no-JavaScript and hydration behaviour need exact definitions and testable properties (PBT-01). Unit 3's logic is covered by Infrastructure Design; it records its properties there
|
||||
- [ ] NFR Requirements - SKIP
|
||||
- **Rationale**: The NFRs are in requirements.md and the stack is decided. PBT-09: fast-check is already a project dependency
|
||||
- [ ] NFR Design - SKIP
|
||||
- **Rationale**: NFR Requirements is skipped; script loading and measurement are settled in Application Design
|
||||
- [ ] Infrastructure Design - EXECUTE for unit 3
|
||||
- **Rationale**: Server rules for URLs and 404 on nginx and IIS, deployed output and upload order change
|
||||
- [ ] Code Generation - EXECUTE (ALWAYS)
|
||||
- **Rationale**: Implementation planning and code generation needed
|
||||
- [ ] Build and Test - EXECUTE (ALWAYS)
|
||||
- **Rationale**: Build, test and verification needed, including the human task on the Pi
|
||||
|
||||
### 🟡 OPERATIONS PHASE
|
||||
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP
|
||||
- **Rationale**: Operations Configuration = No. Necessary server and CI changes are part of unit 3
|
||||
|
||||
## Units of Work
|
||||
|
||||
| Unit | Content | Requirements | Depends on |
|
||||
|---|---|---|---|
|
||||
| 1. Start migration and script step | Start setup, entry and root document, head tags, post-build script step and guard, hydration of all pages, Sentry and Umami, tests, CI output path and preview | FR-PR-01 to 08, 19, 20, 22; catch-all route of FR-PR-14 and 15; NFR-PR-P-03, P-04, S-02, SEC-01 to 04, Q-01 to 05 | None |
|
||||
| 2. Fade-in, no JavaScript, first photo | `Reveal`, `DeferredImage`, mobile menu without JavaScript, carousels and form fallback, photo preload | FR-PR-09 to 13, 21 | Unit 1 |
|
||||
| 3. Hosting and targets | URLs without a redirect, real 404, nginx and IIS configuration, upload order, Lighthouse targets | FR-PR-14 to 18; NFR-PR-P-01, P-02, S-01 | Units 1 and 2 |
|
||||
|
||||
**Decision gate after unit 1 (NFR-PR-P-03)**: bundle size and Lighthouse scores are measured against master and shown to the owner. If they got worse, the owner decides whether to continue with Start before units 2 and 3 start.
|
||||
|
||||
## Package Change Sequence
|
||||
Single package (`web/`). Units run in sequence; unit 3 sets the final Lighthouse targets, so it comes last.
|
||||
|
||||
## Estimated Timeline
|
||||
- **Total Stages Remaining**: 5 (Application Design, Functional Design, Infrastructure Design, Code Generation, Build and Test)
|
||||
- **Estimated Duration**: No fixed estimate. Each push to the pull request starts a full CI run of about 20 minutes on the Pi
|
||||
|
||||
## Success Criteria
|
||||
- **Primary Goal**: All pages arrive as complete HTML, with better first paint and full crawlable content, under the unchanged CSP
|
||||
- **Key Deliverables**: Start-based build, post-build script step with guard, adjusted components, updated server configuration and CI, new Lighthouse targets
|
||||
- **Quality Gates**: `pnpm check` and CI pass; browser test of hydration under the production CSP; no-JavaScript content test; owner decisions recorded for any page below 0.9
|
||||
- **Integration Testing**: Built output tested on nginx (test environment) and against the IIS configuration
|
||||
- **Operational Readiness**: Monitoring keeps working (FR-PR-08); no new monitoring is added
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
# Verduidelijkingsvragen: prerendering
|
||||
|
||||
Twee van je antwoorden hebben nog een keuze nodig voordat ik de requirements kan schrijven. Je overige antwoorden zijn verwerkt.
|
||||
|
||||
## Tegenstrijdigheid 1: TanStack Start en de CSP
|
||||
|
||||
Je koos TanStack Start (vraag 2, B). Een vast uitgangspunt was dat de CSP ongewijzigd blijft. Die twee botsen, zoals een kleine proef-app laat zien: TanStack Start 1.169.4 met Chakra, getest in Chrome met onze `script-src`.
|
||||
|
||||
**Wat de proef liet zien:**
|
||||
|
||||
- **Statische HTML werkt:** Start maakt per pagina een HTML-bestand met de inhoud en de Chakra-stijlen, zonder Node-server. De bestanden komen in `dist/client` te staan, dus CI en deployment moeten mee veranderen.
|
||||
- **Inline scripts:** elke pagina krijgt twee inline scripts. Het eerste bevat paginagegevens, waardoor de hash per pagina verschilt.
|
||||
- **Met onze huidige CSP breekt de site:** de browser blokkeert de scripts, de app crasht en de inhoud verdwijnt van het scherm.
|
||||
- **Scripts in eigen bestanden werken:** als een stap na de build die scripts naar eigen bestanden in `/assets` verplaatst, blijft de CSP gelijk. De knop en de link werkten dan, zonder CSP-meldingen.
|
||||
- **Meer JavaScript:** de hoofdbundel van de proef is 165 kB gzip, bijna zonder eigen code. De huidige site, inclusief al zijn code, is ongeveer 149–153 kB. Dit is een grove vergelijking, maar Start lijkt de bundel groter te maken, en dat werkt tegen het Lighthouse-doel van vraag 7.
|
||||
|
||||
### Verduidelijkingsvraag 1
|
||||
|
||||
Hoe lossen we dit op?
|
||||
|
||||
- A) Start gebruiken, met een stap na de build die de inline scripts naar eigen bestanden verplaatst. De CSP blijft gelijk. Nadeel: we leunen op hoe Start zijn scripts schrijft, dus een test moet dit bij elke upgrade bewaken, en elke pagina krijgt twee kleine extra verzoeken. Aanbevolen als je bij Start wilt blijven; dit is ook in de proef bewezen.
|
||||
- B) Start gebruiken en de hashes van alle pagina's in de CSP zetten. Geen extra verzoeken, maar de CSP verandert bij elke inhoudswijziging, en de nginx-config op de Pi moet nu met de hand worden bijgewerkt. Dat is dus niet praktisch zonder ook die config te automatiseren.
|
||||
- C) Toch de eigen Vite-build-stap (vraag 2, A). Geen inline scripts en waarschijnlijk minder JavaScript, maar geen standaardframework. Dit is ook de beste optie als de score het zwaarst weegt.
|
||||
- D) `'unsafe-inline'` toestaan in `script-src`. Het is het eenvoudigst, maar verzwakt de bescherming tegen XSS en vraagt een gedocumenteerde uitzondering op SECURITY-04. Niet aanbevolen.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Onduidelijkheid 1: wat doet de build-trigger?
|
||||
|
||||
Je koos ervoor nu al een manier in te bouwen om de build van buitenaf te starten (vraag 8, B). De CI-workflow heeft al een handmatige start (`workflow_dispatch`) met de keuzes `deploy_test` en `deploy_production`. Productie kan daarmee alleen vanaf een `release/*`-branch. Nog niet duidelijk is hoe ver een trigger mag gaan.
|
||||
|
||||
### Verduidelijkingsvraag 2
|
||||
|
||||
Wat moet een trigger van buitenaf kunnen?
|
||||
|
||||
- A) De bestaande `workflow_dispatch` hergebruiken en documenteren: een aanroep met een token met zo min mogelijk rechten bouwt en zet het resultaat op test. Productie blijft een handmatige stap. Aanbevolen: er komt niets nieuws bij om te beveiligen, en er gaat niets ongezien live. Of onze Gitea-versie deze aanroep ondersteunt, controleer ik nog.
|
||||
- B) Zoals A, maar de trigger mag ook naar productie deployen, na de bestaande controles en Lighthouse. Een wijziging in het CMS staat dan automatisch live, maar het token wordt gevoeliger en de `release/*`-regel moet worden aangepast.
|
||||
- C) Een eigen webhook-endpoint dat de build start. Dit vraagt een server die openbaar bereikbaar is, en die hebben we nu niet.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: x, moet er van buiten getriggert worden? Front-end triggeren is voor nu prima want pagina-teksten worden grotendeels vast. de CMS zal alleen gallerijen, pakketten etc doen, maar de belangrijkste teksten worden mogelijk niet aanpasbaar in het CMS. Als dat wel zo is kunnen we tegen die tijd kijken hoe we dat gaan doen
|
||||
+129
@@ -0,0 +1,129 @@
|
||||
# Vragen bij de requirements: prerendering
|
||||
|
||||
Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom.
|
||||
|
||||
**Wat prerendering hier betekent:** nu krijgt een bezoeker een lege `index.html` en bouwt JavaScript daarna de pagina op. Met prerendering maakt de build voor elke pagina vast een HTML-bestand met de volledige inhoud. De browser en Google zien de tekst en foto's dan meteen, en daarna maakt React de pagina interactief ("hydration").
|
||||
|
||||
**Vaste uitgangspunten, hierover hoef je niets te beslissen:**
|
||||
|
||||
- De URL's blijven gelijk, dus zonder `/` aan het eind (`/over-mij`).
|
||||
- De hosting blijft statisch: nginx op test en IIS op productie, zonder Node-server.
|
||||
- De strenge beveiligingsheaders (CSP) blijven zoals ze zijn.
|
||||
- Links met een zoekparameter, zoals `/?pakket=...` en `/portfolio?shoot=...`, blijven werken.
|
||||
|
||||
## Vraag 1
|
||||
|
||||
Welke pagina's krijgen een eigen vooraf gebouwd HTML-bestand?
|
||||
|
||||
- A) Alle bestaande pagina's: de 10 geïndexeerde pagina's plus `/privacyverklaring` (aanbevolen: één werkwijze voor de hele site)
|
||||
- B) Alleen de 10 geïndexeerde pagina's; `/privacyverklaring` blijft client-side
|
||||
- C) Eerst alleen de homepage en de foto-pagina's die nu onder het Lighthouse-doel zitten
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 2
|
||||
|
||||
Met welke techniek bouwen we de HTML?
|
||||
|
||||
- A) Een eigen build-stap met Vite: React rendert elke route naar HTML en de bestaande app blijft verder hetzelfde. Dit is aanbevolen, want het is de kleinste wijziging, er zijn geen inline scripts nodig die de CSP blokkeert, en de pagina's halen nu nergens data op die mee moet.
|
||||
- B) Overstappen op TanStack Start, het framework bij onze router, met statische prerendering. Dit is meer standaard, maar een grotere ombouw, en de inline scripts kunnen botsen met de CSP (nog te controleren).
|
||||
- C) Na de build elke pagina in een headless browser openen en de HTML opslaan. De code blijft ongewijzigd, maar elke build heeft dan Chromium nodig en de opgeslagen stijlen en toestand zijn kwetsbaarder.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 3
|
||||
|
||||
Veel blokken faden nu in bij het scrollen (`Reveal`, 21 keer in 14 bestanden) en zijn tot dan onzichtbaar. In vooraf gebouwde HTML zouden ze onzichtbaar blijven totdat de JavaScript draait, en dat kost juist de snelheidswinst. Wat moet er gebeuren?
|
||||
|
||||
- A) De animatie blijft, maar wat bij het laden al in beeld is, staat er direct zonder fade-in. Lager op de pagina blijft de fade-in werken. Aanbevolen: zo blijft het effect bestaan en verschijnt de eerste foto meteen. Dit vervangt je eerdere keuze om de fade-in op de eerste foto van de shootpagina's te laten staan.
|
||||
- B) De fade-in overal behouden zoals nu, ook bovenaan. De grootste foto verschijnt dan nog steeds pas na de JavaScript, dus de winst op die pagina's blijft beperkt.
|
||||
- C) De fade-in overal verwijderen
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 4
|
||||
|
||||
Wat moet er werken bij een bezoeker of crawler zonder JavaScript?
|
||||
|
||||
- A) Alle tekst, foto's en links zijn zichtbaar en werken. Menu's op mobiel, de slider, de lightbox en het formulier hebben JavaScript nodig. Aanbevolen: dit dekt SEO en link-previews zonder dat we onderdelen dubbel moeten bouwen.
|
||||
- B) Zoals A, maar het mobiele menu werkt ook zonder JavaScript. Dat kost extra bouw- en testwerk.
|
||||
- C) Geen eis: alleen de HTML voor crawlers telt, ook als er zonder JavaScript onderdelen verborgen blijven
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 5
|
||||
|
||||
Een onbekende URL krijgt nu de app terug met HTTP-status 200, en de router toont daarna de 404-pagina. Google kan dat zien als een "soft 404". Wat wil je?
|
||||
|
||||
- A) Een vooraf gebouwde 404-pagina met een echte HTTP-status 404, op nginx én IIS (aanbevolen: goed voor SEO, en de serverconfig wordt toch al aangepast). De twee extra knoppen op de 404-pagina onder `/soorten-fotoshoots/` blijven: de pagina kan die pas in de browser tonen, omdat ze afhangen van de opgevraagde URL.
|
||||
- B) Zo laten en dit later apart oppakken
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 6
|
||||
|
||||
Horen responsive foto's (meerdere formaten per foto, zodat een telefoon kleinere bestanden laadt) bij deze feature? In `lighthouserc.cjs` staat dat minder bytes aan foto's de score op de gemeten foto-pagina's niet verbeterden, en de homepagefoto's zijn nog niet responsive.
|
||||
|
||||
- A) Nee, alleen prerendering, plus een preload van de belangrijkste foto per pagina. Responsive foto's worden een aparte feature. Aanbevolen: het houdt deze feature klein en laat apart zien wat prerendering oplevert.
|
||||
- B) Ja, responsive foto's horen er meteen bij
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 7
|
||||
|
||||
De Lighthouse-doelen voor mobiel zijn tijdelijk verlaagd "tot prerendering" (homepage 0,8, foto-pagina's 0,85). Prerendering versnelt het eerste beeld, maar de hoeveelheid JavaScript blijft gelijk, dus 0,9 is niet gegarandeerd. Wat is het doel?
|
||||
|
||||
- A) Mikken op 0,9 op alle pagina's. Haalt een pagina dat niet, dan laat ik je de meting zien en beslis jij per pagina. Aanbevolen: het doel blijft ambitieus en we verlagen niets ongemerkt.
|
||||
- B) 0,9 is een harde eis: de feature is pas af als alle pagina's het halen, ook als daar extra werk aan de JavaScript-bundel voor nodig is
|
||||
- C) Geen vast nieuw doel: de doelen verhogen tot wat de metingen laten zien
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 8
|
||||
|
||||
De inhoud staat nu in de code, en later komt er een API/CMS. Met prerendering komt die inhoud vast in de HTML te staan. Hoe gaan we daar nu mee om?
|
||||
|
||||
- A) De HTML wordt bij elke build gemaakt uit de huidige inhoud. Automatisch opnieuw bouwen bij een CMS-wijziging wordt onderdeel van de latere CMS-feature; ik leg dit als aandachtspunt vast. Aanbevolen: het CMS bestaat nog niet, dus we bouwen er nu niets voor.
|
||||
- B) Nu al een manier inbouwen om de build van buitenaf te starten (voorbereiding op het CMS)
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag: Beveiligingsextensies
|
||||
|
||||
Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor deze feature?
|
||||
|
||||
- A) Ja — dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten (aanbevolen voor productietoepassingen, en zo ook gekozen bij shoot-type-pages)
|
||||
- B) Nee — sla alle BEVEILIGINGSREGELS over (geschikt voor PoC's, prototypes en experimentele projecten)
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag: Property-Based Testing Extensie
|
||||
|
||||
Moeten de property-based testing (PBT) regels worden afgedwongen voor deze feature?
|
||||
|
||||
- A) Ja — dwing alle PBT-regels af als blokkerende vereisten (aanbevolen voor projecten met bedrijfslogica, datatransformaties, serialisatie of stateful componenten; zo ook gekozen bij shoot-type-pages)
|
||||
- B) Gedeeltelijk — dwing PBT-regels alleen af voor pure functies en serialisatie round-trips (geschikt voor projecten met beperkte algoritmische complexiteit)
|
||||
- C) Nee — sla alle PBT-regels over (geschikt voor eenvoudige CRUD-applicaties, UI-only projecten of dunne integratielagen zonder significante bedrijfslogica)
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag: Operations-fase
|
||||
|
||||
Moet deze feature na Construction door de Operations-fase (deployment en monitoring inrichten)? De aanpassingen aan de serverconfig en CI-workflow horen sowieso bij Construction. Alleen de nginx-config op de Pi moet daarna nog met de hand worden bijgewerkt.
|
||||
|
||||
- A) Ja — na Construction de Operations-fase uitvoeren (deployment en monitoring inrichten)
|
||||
- B) Nee — stoppen na Build and Test (aanbevolen: de bestaande deployment en monitoring blijven gelijk, en zo ook gekozen bij shoot-type-pages)
|
||||
- C) Weet ik nog niet — vraag het opnieuw na de Construction-fase
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
@@ -0,0 +1,148 @@
|
||||
# Requirements: prerendering
|
||||
|
||||
## Intent Analysis
|
||||
|
||||
- **User request**: "Ik wil een nieuwe feature toevoegen met aidlc. Namelijk de pre-rendering voor het verbeteren van performance en SEO."
|
||||
- **Request type**: Enhancement with a framework migration (SPA with a plain Vite entry to TanStack Start with static prerendering)
|
||||
- **Scope estimate**: System-wide within `web/`: app entry, root route, build, server configuration, CI, Lighthouse, and shared display components
|
||||
- **Complexity estimate**: Complex (framework change, hydration behaviour, strict CSP, two web servers)
|
||||
- **Depth**: Standard
|
||||
|
||||
## Goal
|
||||
|
||||
Every page is delivered as a complete HTML file, so visitors see content before the JavaScript runs and crawlers receive full text, links and metadata without executing JavaScript. The site stays statically hosted and its security headers stay as strict as they are now.
|
||||
|
||||
## Decisions
|
||||
|
||||
| Topic | Decision | Source |
|
||||
|---|---|---|
|
||||
| Pages | All 11 pages: 10 indexed plus `/privacyverklaring` | Q1 A |
|
||||
| Technique | TanStack Start with static prerendering | Q2 B |
|
||||
| CSP conflict | A post-build step moves Start's inline scripts to files in `/assets`; CSP unchanged | Clarification 1 A |
|
||||
| Fade-in | Content in view at load appears at once; fade-in remains lower on the page. Replaces the owner's 2026-10-30 choice for the first story block | Q3 A |
|
||||
| Without JavaScript | All text, photos and links work, and the mobile menu works | Q4 B |
|
||||
| 404 | Prebuilt 404 page with a real HTTP 404 on nginx and IIS | Q5 A |
|
||||
| Responsive photos | Out of scope; separate feature | Q6 A |
|
||||
| Lighthouse | Aim for 0.9 everywhere; the owner decides per page on a miss | Q7 A |
|
||||
| External build trigger | Not built. Page texts are largely fixed and the frontend is rebuilt through the normal flow. Revisit if the CMS makes such texts editable | Q8 B, narrowed by Clarification 2 |
|
||||
| Extensions | Security Baseline and Property-Based Testing fully enforced | Opt-in |
|
||||
| Operations phase | No | Opt-in |
|
||||
|
||||
## Target Build Flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Source["Routes and content"] --> Start["TanStack Start build with prerender"]
|
||||
Start --> Html["HTML per page, including 404"]
|
||||
Html --> Extract["Post-build step: inline scripts to /assets"]
|
||||
Extract --> Guard["Build check: no executable inline script left"]
|
||||
Guard --> Client["dist/client: deployable output"]
|
||||
Start -.-> Server["dist/server: build only, never deployed"]
|
||||
Client --> Nginx["nginx on test"]
|
||||
Client --> Iis["IIS on production"]
|
||||
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef check fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef output fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef excluded fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
|
||||
class Source,Start,Html,Extract build;
|
||||
class Guard check;
|
||||
class Client,Nginx,Iis output;
|
||||
class Server excluded;
|
||||
```
|
||||
|
||||
Text alternative: Start renders each page to HTML, a post-build step moves inline scripts to files, a check guards the result, and only `dist/client` goes to nginx and IIS; `dist/server` is never deployed.
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### Prerendered pages
|
||||
|
||||
- **FR-PR-01**: The build produces an HTML file for each of these pages, containing the page's full text, photo elements and links: `/`, `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, the five `/soorten-fotoshoots/{newborn,zwangerschap,gezin,loveshoot,portret}` pages, `/contact` and `/privacyverklaring`.
|
||||
- **FR-PR-02**: Each HTML file contains that page's own title, description, canonical URL, Open Graph tags and JSON-LD, without duplicate tags. The static fallback tags in `web/index.html` and their removal in `web/src/main.tsx` are no longer needed.
|
||||
- **FR-PR-03**: A new route cannot be left out unnoticed: the build or a test fails when a page in `sitePages.ts` has no prerendered HTML file.
|
||||
- **FR-PR-04**: `sitemap.xml` keeps its current content, and `/privacyverklaring` stays `noindex`.
|
||||
|
||||
### Behaviour after loading
|
||||
|
||||
- **FR-PR-05**: Every page becomes fully interactive after hydration, with no hydration errors in the browser console. Components whose output depends on the browser, such as media queries with `ssr: false` in `NavigationBar` and `useReveal`, must not cause a mismatch or a visible jump.
|
||||
- **FR-PR-06**: Links with search parameters keep working: `/?pakket=...`, `/contact?pakket=...` and `/portfolio?shoot=...` show the same result as today, with the prerendered HTML as their first paint.
|
||||
- **FR-PR-07**: Client-side navigation, scroll restoration, focus handling on route change, `/?pakket=...#contact` anchors and the error page behave as they do now.
|
||||
- **FR-PR-08**: Sentry and Umami still start only in the browser and only on the test and production hostnames.
|
||||
|
||||
### Fade-in
|
||||
|
||||
- **FR-PR-09**: `Reveal` content is visible in the prerendered HTML. After loading, content already in view stays visible without animation; content below the viewport fades in on scroll as it does now. Because the build cannot know the visitor's screen size, this is decided in the browser, without first hiding content that is in view.
|
||||
- **FR-PR-10**: With reduced motion, content is visible without animation, as it is now.
|
||||
|
||||
### Without JavaScript
|
||||
|
||||
- **FR-PR-11**: Without JavaScript, all text and photos are visible, including `Reveal` content and photos loaded through `DeferredImage`, and all links work. Exception: the e-mail address and its links appear only after hydration (FR-PR-22).
|
||||
- **FR-PR-12**: Without JavaScript, the mobile menu opens and closes and every link in it can be reached, including the shoot submenu. Keyboard and screen reader behaviour with JavaScript stays as it is.
|
||||
- **FR-PR-13**: The hero slider, testimonial carousel, lightbox and contact form may require JavaScript, but without it they show usable content: at least the first slide and the photos.
|
||||
- **FR-PR-22**: The e-mail address stays out of the prerendered HTML and the serialized data, in readable and in mailto form, so the existing protection against harvesting remains. It appears after hydration. A build check fails if the assembled address occurs in any HTML file. Owner's decision (start-migration-fd-questions.md, A).
|
||||
|
||||
### Not found
|
||||
|
||||
- **FR-PR-14**: A prebuilt 404 page is served with HTTP status 404 for unknown URLs on nginx, IIS and the preview server used by Lighthouse. It is `noindex`.
|
||||
- **FR-PR-15**: The existing 404 behaviour stays: under `/soorten-fotoshoots/` the two extra buttons appear (FR-ST-14), decided in the browser from the requested URL.
|
||||
|
||||
### URLs and hosting
|
||||
|
||||
- **FR-PR-16**: Page URLs stay without a trailing slash and are served directly with status 200, without a redirect. The nginx and IIS configuration stays generated from `web/config/serverConfig.ts`.
|
||||
- **FR-PR-17**: Only the client output is deployed to test and production. The Node server output from the build is never uploaded.
|
||||
- **FR-PR-18**: During a production upload, a visitor never receives HTML that refers to a file not yet present. The existing order (assets first, then HTML, then cleanup) must cover all HTML files instead of only `index.html`. HTML stays uncached and hashed assets stay long-cached.
|
||||
|
||||
### Inline scripts
|
||||
|
||||
- **FR-PR-19**: A post-build step moves every executable inline script in the generated HTML to a file in `/assets`, preserving execution order. JSON-LD data blocks stay inline, provided a browser test confirms the CSP does not block them.
|
||||
- **FR-PR-20**: The build fails if an executable inline script remains in any HTML file, or if the step finds no scripts where it expects them, so a Start upgrade that changes the output format is noticed.
|
||||
|
||||
### First photo
|
||||
|
||||
- **FR-PR-21**: Each page whose largest visible element is a photo preloads that photo from the HTML.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
|
||||
- **NFR-PR-P-01**: The mobile Lighthouse performance target is 0.9 on all pages. The temporary exceptions in `web/lighthouserc.cjs` (home 0.8, photo pages 0.85) are removed for each page that reaches 0.9. For a page that misses it, the owner sees the measurement and decides; no target is lowered or left in place without that decision.
|
||||
- **NFR-PR-P-02**: The desktop target stays 0.9.
|
||||
- **NFR-PR-P-03**: The main bundle size and Lighthouse scores are measured before the change and after the first unit, and reported to the owner. If the framework change makes scores worse, the owner decides whether to continue before further work is built on it.
|
||||
- **NFR-PR-P-04**: The moved scripts must not noticeably delay first paint. The effect is measured, and the design considers where they load.
|
||||
|
||||
### SEO and accessibility
|
||||
|
||||
- **NFR-PR-S-01**: Lighthouse accessibility, best practices and SEO stay at 1.0, as currently enforced.
|
||||
- **NFR-PR-S-02**: Fetching any page without JavaScript returns its title, h1, main text and internal links in the HTML. An automated test checks this for all pages.
|
||||
|
||||
### Security
|
||||
|
||||
- **NFR-PR-SEC-01**: `script-src` and the rest of the production CSP stay unchanged. Pages run without CSP violations in a real browser under the production headers.
|
||||
- **NFR-PR-SEC-02**: New dependencies are in the lockfile, pass `pnpm audit:deps`, and keep the existing `seroval` overrides in `pnpm-workspace.yaml`. Unused dependencies are removed.
|
||||
- **NFR-PR-SEC-03**: Nothing from the server build, source maps of server code or build paths ends up in the deployed output. Error pages show no internal details.
|
||||
- **NFR-PR-SEC-04**: Serialized data in the HTML contains only public page data.
|
||||
|
||||
### Quality
|
||||
|
||||
- **NFR-PR-Q-01**: `pnpm check` and CI pass, with the existing coverage thresholds. The existing test suite keeps running; test setup changes only where the framework change requires it.
|
||||
- **NFR-PR-Q-02**: Pure logic in the post-build step is covered by example-based tests and fast-check property tests. Candidates are preserved script order, idempotence and unchanged data blocks; Functional Design confirms the list (PBT-01).
|
||||
- **NFR-PR-Q-03**: A browser test verifies hydration and interaction under the production CSP against the built output, and runs in CI.
|
||||
- **NFR-PR-Q-04**: The visual result matches the current site, with no flash of unstyled content. Chakra's styles are present in the HTML.
|
||||
- **NFR-PR-Q-05**: Comments and documentation explain why the post-build step exists, and the shared reverse-engineering lines for this feature are updated.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Responsive photos (separate feature)
|
||||
- An external build trigger or webhook
|
||||
- CMS or API integration
|
||||
- The draft shoot page texts and photos (`features/shoot-type-pages/content-pending.md`); they are prerendered as they are at build time
|
||||
|
||||
## Risks and Attention Points
|
||||
|
||||
| Risk | Consequence | Handling |
|
||||
|---|---|---|
|
||||
| Start increases the JavaScript: the spike's main bundle was 165.0 kB gzip with almost no app code, versus about 149–153 kB for the current site. A rough comparison | Less Lighthouse gain than hoped | NFR-PR-P-03: measure early; owner decides |
|
||||
| The post-build step depends on Start's output format | An upgrade can break the site | FR-PR-20 and NFR-PR-Q-03 |
|
||||
| Community reports of Emotion styling problems with Start's SSR; the spike showed styles in the HTML, but flicker on a real page is untested | Visible jump on load | NFR-PR-Q-04, checked in the first unit |
|
||||
| The spike covered two simple pages, not this app's own components | Unknown hydration problems | First unit runs the real app |
|
||||
| The nginx configuration on the Pi is updated by hand | Test shows old 404 or URL behaviour until updated | **HUMAN TASK**, documented in Build and Test |
|
||||
| Later CMS content (galleries, packages) ends up in static HTML | Published changes stay invisible until a rebuild, unless fetched in the browser | Decide in the CMS feature; owner expects most page texts to stay fixed |
|
||||
Reference in New Issue
Block a user