Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/inception/requirements/requirements.md
T
SluijsensandClaude Opus 5.5 0c5d8b8f40 Compresses responses in the preview server
The baseline ran on vite preview, which compresses, so measurements could not
be compared without this. Also records that the real servers need compression.

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

151 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
- **FR-PR-23**: nginx and IIS serve text responses (HTML, JavaScript, CSS, SVG, JSON, XML) compressed. Measured on 2026-10-31: `test.andreaslop.nl` returned HTML and JavaScript without `Content-Encoding` and the generated server configuration has no compression rules; the cause on the test host (nginx or its reverse proxy) is settled in Infrastructure Design. Added by the main session as a consequence of the goal; the owner can overrule it.
### 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 |