Repository navigation
Public sites performance: caching strategy and page weight #75
Description
Make FrontLit public sites (apps/sites) fast by default and in line with industry standards for hosted docs and marketing portals. Everything must work when self-hosted: the cache lives inside FrontLit, and a CDN is an optional extra in front of it, never required for correct delivery.
Today
- Every request renders on demand. The tenant layout reads request headers (
x-frontlit-embed,x-frontlit-canonical-host), so Next can't cache whole pages. The only caching is a 60-second, per-pod data cache. - Docs are never cached. They use
no-storeend to end, so every docs view hits the API and database. revalidateTagonly reaches one replica. The webhook clears the cache on the pod that receives it; the data and host caches are per pod.- The whole page is a client component. The page-builder renderer is shipped to and run in the browser.
- Images are served at full size. Raw
<img>, MediaLit originals, no resizing.
Decisions
- MediaLit serves public media through its CDN when configured. It is not the edge cache/CDN for FrontLit site responses (HTML and RSC); Layer 2 caches those responses and uses FrontLit’s invalidation flow. MediaLit remains the media storage and delivery layer.
- Every caching layer must be self-hosting friendly and vendor-neutral.
- Docs drop the "zero staleness / no-store" rule (
docs-management.md§23.3). They are cached and invalidated on publish via the signed outbox webhook; staleness is bounded by webhook delivery, normally under a second. Search, chat and the public docs API stay authoritative and uncached.
Phases
- Public sites perf · Phase 1: page weight (server-rendered blocks, lazy chat, images, fonts) #71 Phase 1: page weight. No infrastructure needed.
- Public sites perf · Phase 2: built-in caching layer (cache components + shared Redis handler, docs cacheable) #72 Phase 2: built-in caching layer (Layer 1). Can run alongside Phase 1.
- Public sites perf · Phase 3: optional, vendor-neutral edge cache / CDN support #73 Phase 3: optional, vendor-neutral edge cache / CDN support (Layer 2).
- Public sites perf · Phase 4: hosted CDN adapter #74 Phase 4: hosted CDN adapter (hosted FrontLit only).
Targets
- Cache hit ratio above 95%.
- TTFB p75 under 100ms on cache hits.
- LCP under 1.5s, CLS under 0.1, INP under 200ms.
Activity
clbotdev commentedon Oct 25, 2026
Status and measured results. Same sample tenant throughout: 9-block homepage with 8 images, 12 docs, 7 posts. Local machine; Lighthouse mobile, median of 5.
ttlmode capped at the TTL. Fixed an RSC cache-poisoning case behind Vary-ignoring CDNsPhase 1 (#78) against the commit before it:
Against the targets:
PRs #143 → #144 → #145 are stacked; #142 is independent.
clbotdev commentedon Oct 25, 2026
#142–#145 are merged; Phases 1–3 are done. Phase 4 (#74) is waiting on the vendor and custom-domain TLS decisions (recommendation in docs/site-delivery.md §7a). The Cloudflare adapter and RUM are already on main.