Files
slp-modular-cms/WEBSITE_WORKSPACE.md
T
SluijsensandClaude Sonnet 5.5 7d21d9024a Voeg WebsiteMode.PrerenderedPages toe: nginx-gelijke serving van een voorgerenderde website
- Pure WebsitePathResolver (canonieke 301's, echte 404, dotfiles geweigerd, gereserveerde prefixes)
- PrerenderedSiteMiddleware, 404-fallback na de API-routes, gzip, Cache-Control, NoIndex/robots.txt
- Beleid StrictSite met eigen AllowedSite*Origins; volledige headerset op alle websiteresponses
- Tests: voorbeelden, FsCheck-properties en integratietests op een in-memory server

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-06 15:52:04 +01:00

6.4 KiB

Website Workspace Contract

Dit document is voor wie de publieke website bouwt die naast de SlpModularCms-admin draait. Je hoeft de rest van deze repository niet te lezen om een werkende site te kunnen opleveren — dit contract is compleet genoeg om zelfstandig te volgen.

Doelpad

De website hoort in wwwroot/web/, in de root van de gepubliceerde applicatie. Dit pad moet minimaal een index.html bevatten. Alles onder wwwroot/web/ is van jou — de applicatie zelf raakt deze map nooit aan buiten het plaatsen van de bestanden die je aanlevert, en een CMS-deploy verwijdert of overschrijft de inhoud nooit (zie "Waarom dit veilig is" hieronder).

wwwroot/
  web/            ← jouw site komt hier (dit contract)
    index.html    ← verplicht
    assets/...
    ...
  admin/          ← VERBODEN — dit is de CMS admin-UI, hoort niet bij deze repo

Verboden en gereserveerde paden

Verboden — plaats hier nooit bestanden:

  • wwwroot/admin/ — dit is de CMS admin-single-page-app, wordt door deze repository zelf beheerd en bij elke build overschreven
  • De applicatie-root zelf (waar de .dll-bestanden van de API staan)

Gereserveerd — deze paden bestaan al en je site mag er niet mee botsen:

  • /admin — de CMS admin-UI
  • /api/v1 — de backend-API
  • /health — infrastructuur-liveness-check (zie hieronder — dit is geen CMS-functionaliteit)

Als jouw site een eigen route of bestand op een van deze paden zou plaatsen, wint de gereserveerde route altijd.

Routing (SPA-fallback)

Voor paden die geen bestandsextensie hebben (bijv. /over-ons, /producten/123) valt de applicatie terug op wwwroot/web/index.html — zo werkt client-side routing (React Router, Vue Router, of vergelijkbaar) zoals verwacht. Voor paden die er wél uitzien als een bestand (bijv. /assets/logo.png) geldt geen fallback: ontbreekt het bestand, dan krijg je gewoon een 404, niet per ongeluk de index.html.

Dit betekent: bouw je een Single Page Application, dan hoeft je routing-configuratie niets speciaals te doen voor deze server — de fallback wordt door de applicatie zelf verzorgd.

Alternatief: voorgerenderde site (WebsiteMode = PrerenderedPages)

Een client kan kiezen voor een voorgerenderde meerpaginasite (elke pagina is een eigen .html-bestand) in plaats van de SPA-fallback hierboven. Dat is een keuze van de client (new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages } in zijn Program.cs); zonder die keuze verandert er niets. De host serveert dan zoals nginx dat deed:

Verzoek Resultaat
/ index.html
/over-mij over-mij.html (ook map/index.html als map.html ontbreekt)
/Over-Mij, /over-mij.html, /over-mij/ één 301 naar /over-mij (query blijft behouden; relatieve Location)
/index, /index.html 301 naar /
elk ander pad met slash aan het eind 301 naar het pad zonder slash (ook als dat niet bestaat; daarna volgt de 404)
bestand met extensie (/assets/app.abc.js) het bestand zelf; nooit omgezet naar kleine letters of doorgestuurd; ontbreekt het, dan 404
onbekend pad, /404, /404.html, map zonder pagina 404.html met status 404 (bestaat 404.html niet: kale 404); nooit index.html
pad met een segment dat met een punt begint (/.env, /.git/...) 404; alleen /.well-known/... blijft bereikbaar
/admin, /api/v1, /health nooit door de website afgehandeld; een onbekend /api/v1-pad blijft een API-404

Caching: pagina's en overige rootbestanden Cache-Control: no-cache, alles onder /assets/ public, max-age=31536000, immutable. Tekstbestanden (html, css, js, svg, json, xml, txt) worden met gzip gecomprimeerd (geen Brotli). De pagina's worden per verzoek bij het bestandssysteem opgezocht, zonder cache: een nieuwe website-deploy is direct zichtbaar, zonder herstart van de host.

Headers: elke websiterespons (pagina, asset, 301, 404, robots.txt) krijgt de volledige set (CSP, HSTS, nosniff, X-Frame-Options, Referrer-Policy). Het beleid is StrictSite: dezelfde CSP als de site nu heeft (script-src 'self' plus de origins uit SecurityHeaders:AllowedSiteScriptOrigins, connect-src 'self' plus SecurityHeaders:AllowedSiteConnectOrigins). Die twee lijsten gelden alleen voor StrictSite; de admin-policies worden er niet soepeler van.

Een testinstantie zet Website:NoIndex = true: dan krijgt elke websiterespons X-Robots-Tag: noindex, nofollow en geeft /robots.txt User-agent: * / Disallow: /.

De API aanroepen

Roep /api/v1/... aan met relatieve URL's (bijv. fetch('/api/v1/System/capabilities')). Omdat je site en de API door hetzelfde proces op dezelfde origin worden geserveerd, is dit een same-origin request — er is geen CORS-configuratie nodig, en er hoeft niets ingesteld te worden om dit te laten werken.

Content-Security-Policy

Jouw site valt onder het Relaxed-beleid (de standaardpolicy voor alle paden die niet expliciet Strict zijn — /admin, /api/v1 en /health krijgen Strict, / (jouw site) niet). Dit beleid is bewust minder streng, zodat je niet gebonden bent aan restricties die voor de CMS-admin gelden maar die je als website-bouwer nooit zou hoeven kennen. De exacte permissieve/strikte policy-definities staan in code (SlpModularCms.Core), niet in configuratie — je hoeft ze niet zelf te lezen om te weten dat je site onder het permissieve beleid valt.

Umami-analytics insluiten

Als de instantie analytics gebruikt, wordt het Umami-trackingscript geladen via een build-time omgevingsvariabele op de admin-kant (VITE_UMAMI_SCRIPT_URL / VITE_UMAMI_WEBSITE_ID) — dat script wordt dus niet door jouw site zelf ingesloten. Wil je dat jouw website ook gemeten wordt via dezelfde Umami-instantie, vraag dan de scriptregel en het bijbehorende website-ID op bij wie de CMS beheert, en neem die regel zelf op in je index.html (Umami's standaard <script>-snippet). Dit contract schrijft niets voor over jouw eigen analytics-keuze — dit is puur de informatie die je nodig hebt als je bij dezelfde Umami-instantie wilt aansluiten.

Waarom dit veilig is

Een deploy van de CMS zelf gebeurt via een atomische release-switch: een nieuwe release komt in een verse map te staan en pas daarna wisselt de actieve release in één keer over. wwwroot/web/ staat buiten die verwisselde map en wordt er telkens in gelinkt — een CMS-deploy kan je site dus structureel niet raken, ongeacht hoe vaak de CMS zelf wordt bijgewerkt.