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

12 KiB
Raw Blame History

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

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