The prerendered hero is plain HTML between the markers (first photo, h1, buttons), the slider takes over after hydration with the hero of the host block, the API or the build. The head preload is added to the finished HTML. Hero texts move into nl.json. The stand-in host and the e2e tests cover the hero. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
14 KiB
CMS integration
The site talks to the SLP CMS host through its API. On the test host the CMS host serves the site itself, so every call is same-origin (/api/v1/*, CSP connect-src 'self', no CORS). Three things come from the CMS: the shoot packages, two banners and the contact form.
Shoot packages
Source: GET /api/v1/offerings. One list feeds the price cards on the home page and on the pages for each shoot type, the "welke shoot" choices of the contact form and the ?pakket= check, so they can never disagree.
- Any number of packages. The cards are a wrapping flex row. On desktop (
lgand up) every card is a third of the row (calc((100% - 2 * gap) / 3)) and every row is centred, so an incomplete last row (4, 5, 7, 8, 10 cards, ...) sits in the middle. There is no styling per number of cards. On phone and tablet the cards are one column; there is no swipe row. - Mapping (
web/src/lib/offerings.ts, pure functions):slugis the package id (keptzwangerschap,newborn,gezin: they appear in?pakket=and the form),titlethe name, the free price text is read as whole euros ("€ 175", "€ 1.250", "175,-"). A card with an unreadable price, no features or a bad slug is skipped. Order followsdisplayOrder. Emptydescription,priceNoteandctaLabelare accepted and left out of the card. - Where the data comes from, in order:
- At build time
web/config/fetchOfferings.ts(the first step ofpnpm build) asksOFFERINGS_URL(10 s timeout, 2 attempts) and writes the gitignoredweb/src/content/offerings.generated.json. The packages are baked into the prerendered HTML (search engines see the prices, no layout jump). - Without
OFFERINGS_URL, with a CMS that is down or with an unusable answer, the committedweb/src/content/offerings.snapshot.jsonis used. The build never fails and never shows empty prices; the log says which source was used. Tests always use the snapshot. - After hydration
PackagesProvider(web/src/components/PackagesProvider/) asks the CMS once and replaces the baked list only if the answer differs. A network error, time-out (8 s), bad status or invalid answer keeps what was baked. A change in the CMS therefore shows at once; the nightly build only matters for search engines.
- At build time
- Featured package (the star in the CMS admin, field
featured): the card gets a heidegroen rule along its top, a heidegroen border and a small "Uitgelicht" tab on the top edge (PriceCard). The tab is positioned on the border, so the cards of a row keep the same layout. Any number of cards may be featured. - Description, price note and button label (
description,priceNote,ctaLabel) are optional in the CMS and the site does not use them: they are not shown and a card never depends on them (empty,nullor absent all give the same card; covered by tests). - Scheduling in the CMS: the API only returns packages that are live at the moment of the request (switched on and inside their from/to dates), so the site shows them and nothing else. The baked list reflects the moment of the build; the live refresh after hydration corrects it for every visitor, and the nightly build corrects it for search engines. A package that goes live or expires between two builds is therefore right in the browser but can be stale in the HTML until the next build.
- Keep the snapshot current when the real packages change (prices, features), because production builds use it (see "Hosting" below).
Banners (OfferingBanner)
Source: GET /api/v1/offerings/banner?position=top|bottom. No parameter means bottom; 204 means no active banner; an invalid value is 400. Answer fields: title (at most 100 characters), text (at most 300 for bottom, 120 for top), linkLabel, linkUrl (both or neither; https:// or a path on the site with one /) and position. Both banners may be active and visible at the same time.
Under the cards (bottom) |
Above the cards (top) |
|
|---|---|---|
| Component | PriceBanner |
PriceTopBar |
| Look | Light band, thin heidegroen top rule, section-heading title, ornament, deep-green link button | Slim white bar, same hairline and top rule, one line: small capitals title, diamond, text, small underlined link |
| Required | title | title or text (title may be empty) |
| Mapping | mapBanner |
mapTopBanner |
Both follow the same rules as the packages: baked into the HTML at build time, replaced live after hydration, empty fields are hidden, an error or invalid answer keeps what was baked. A 204 hides that banner (the one deliberate exception to "keep what was baked"); the two banners are independent of each other. Neither banner is a package: not in the form choices, not in the package count.
Layout shift: a banner that was not active at the last build is not in the HTML. When it appears live, the content below it moves down by its height once (for the top bar, the cards move). Rebuilding with the banner active (the nightly test build does this) removes the shift. The same holds in reverse when a baked banner is switched off.
Hero (CMS module)
The hero of the homepage comes from the CMS hero module (GET /api/v1/hero); the build bakes one in as the fallback (web/src/content/heroContent.ts, texts in nl.json under hero.baked).
- Markers.
index.htmlhas<!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML-->(first photo as<picture>, theh1with tagline and title, the buttons) and, in the head,<!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD-->(the preload links). The head markers are added to the finished HTML byconfig/heroPreload.ts(React cannot write a comment into the head), as part ofconfig/externalizeInlineScripts.ts. The host rewrites both from live data; the contract isweb/contract/host-injection/hero/(README, seed, golden files shared with the CMS repo). Code:src/lib/hero.ts(mapping),src/lib/heroHtml.ts(HTML and preload). - Data block.
#cms-datagets aherokey (the answer of/api/v1/hero). After hydrationsrc/components/Hero/useHero.tstakes it; without a host block the site asks/api/v1/heroitself (8 s time-out). A missing block, a 204, an error or an answer without a usable slide keeps the baked hero (fail open). - Until hydration the hero is the plain HTML between the markers, styled by the global CSS
.cms-hero-*insrc/theme.ts; the slider (arrows, pause, progress) only exists after hydration, so a visitor without JavaScript sees the first photo and no dead controls. Slides after the first also get AVIF<source>s; the first and the preload are WebP only. - Images. Ratios
wide(3:2) andtall(4:5; portrait screens), chosen by(orientation: portrait); the focus point isobject-position. Alt texts and the slider's aria texts are innl.json(hero); a decorative photo hasalt="". - Stand-in host.
config/hostInjector.ts(preview server and e2e) writes the hero regions and theherokey like the real host;e2e/hostInjection.e2e.tscovers it.
Contact form
GET /api/v1/contact-messages/token and POST /api/v1/contact-messages through the headless web/src/cms-client. The form is behind the switch contactForm.enabled in web/src/content/siteContent.ts (off means the "Binnenkort" gate and no request to the server). Details and the go-live conditions are in aidlc-docs/features/contact-form-cms/ and go-live-checklist.md. Friendly Captcha is off at go-live.
Hosting: the CMS host serves everything
Decision (Bryan, 2026-11-15): the hosting package has one entry per website. The CMS host (Kestrel) is that entry and serves the website itself (the prerendered pages), /admin and /api/v1/*. In production IIS (or the proxy) therefore passes all requests to the CMS host, not only /api/v1/*, and serves no static files or HTML cache of its own. This holds for the test host and for ASF production alike.
- Test (ASF): nginx on the proxy Pi forwards everything for
test.andreaslop.nlto the CMS host (web/deploy/nginx/test.andreaslop.nl.proxy.conf), which serves the site files and the API. Nothing to add. - Production: not in place yet. The generated
web/deploy/iis/web.configand the FTP upload of static files (web/deploy/upload-production.sh) still describe the old idea of IIS serving the files. They have to change with the production hosting: IIS keeps only the redirects (www, HTTPS) and the pass-through to the CMS host, and the prerendereddist/goes to the CMS host's prerendered-pages folder as on test. Security headers then come from the CMS host (as on test). This is part of the production hosting work, not of the packages feature. Until then production builds use the committed snapshot and the live calls fail safely (the baked list stays; the browser console shows a 404 for the API). Change generated server files only inweb/config/serverConfig.tsand runpnpm server-config. - Host injection (built in the site; the host side is the CMS repo's work): the build leaves markers in the prerendered pages and the CMS host fills them from live data, so a CMS change is visible to search engines at once without a rebuild. Contract and plan:
aidlc-docs/features/asf-cms-host-injection/plan.md; golden files for the list HTML:web/contract/host-injection/.- Markers:
<!--CMS:DATA-->+<script type="application/json" id="cms-data">(root document, every page),<!--CMS:OFFERINGS-HTML-->,<!--CMS:BANNER-TOP-HTML-->and<!--CMS:BANNER-BOTTOM-HTML-->regions (home page),<!--CMS:OFFER-JSON-LD slug="...">before the ld+json block of the newborn, zwangerschap and gezin pages, and<span data-cms-price="slug">in their price block. - In the page:
CmsRegionrenders the plain HTML between the markers (lib/cmsHtml.ts, styled by.cms-*rules intheme.ts) and React leaves it alone until hydration, so a host that wrote different data causes no hydration mismatch; after hydration the styled components take over.PackagesProviderreads the data block in the first render after hydration (hostCmsData); a block with"source":"build"is the baked one and counts as "no host data", so the page asks the API as before. The site address comes fromsiteUrlin the block (setSiteUrlinclient.tsx), because the script files cannot be rewritten per host. - Tests: golden files (
src/lib/cmsHtml.test.ts), a stand-in for the host (config/hostInjector.ts, also in the preview server as--cms-data=<json>) and browser tests with it (e2e/hostInjection.e2e.ts: HTML without JavaScript, hydration without errors, banners hidden on 204, JSON-LD price edited or removed, address changed and kept after navigation, unusable data, hostile text).
- Markers:
Environment and variables
| Name | Where | Meaning |
|---|---|---|
OFFERINGS_URL |
build env | Site address that serves the API (for example https://test.andreaslop.nl). Unset gives the snapshot. |
ASF_OFFERINGS_URL_TEST |
Gitea repo variable | Value of OFFERINGS_URL for the test build. Set by SLS, not by feature sessions. |
API_PROXY_TARGET |
dev env | Forwards /api in pnpm dev to a CMS host. |
VITE_SITE_URL |
build env | Address the site presents itself under (canonical, og:*, JSON-LD, sitemap). Only the test build sets it (https://test.andreaslop.nl); unset gives https://andreaslop.nl. |
VITE_CONTACT_FORM_ENABLED |
build env | Opens the contact form when exactly true. Only the test build sets it; unset keeps the form closed (production). Opening it in production needs Bryan's explicit go, after the captcha decision (go-live-checklist.md). |
The production artifact is built without OFFERINGS_URL on purpose: production must never carry the prices of the test CMS.