Homepage Overlay Contract

platformkit-business-modules owns the generic homepage runtime, not tenant-specific homepage experiences.

Boundary

• Shared repo responsibility:
  • resolve the active overlay repo
  • load the localized homepage manifest
  • load overlay-owned homepage template, CSS, JS, and partials
  • render the public page shell with shared metadata, CSP nonce, and asset helpers
• Overlay repo responsibility:
  • the actual homepage UX, layout, copy, styling, and optional client-side behavior
  • any business-specific template partials and assets

Client and demo homepage code must live in the corresponding overlay repo under:

apps/<app>/site/

Manifest

Set the homepage renderer in the overlay manifest:

{
  "site": {
    "homepageRenderer": "overlay_experience"
  }
}

The shared runtime reads:

• homepage.<locale>.json
• fallback homepage.en.json

Overlay Files

The overlay renderer looks for:

• template:
  • homepage.<locale>.template.html
  • homepage.template.html
  • homepage.html
• styles:
  • homepage.<locale>.css
  • homepage.css
• scripts:
  • homepage.<locale>.js
  • homepage.js
• partials:
  • site/partials/*.html

The template receives the shared homepageDocument plus:

• .Overlay.ClientSlug
• .Overlay.AssetBase

Overlay-owned homepage CSS is linked from:

• /assets/overlays/<slug>/homepage.<locale>.css
• /assets/overlays/<slug>/homepage.css

Only .css and .js files from apps/<app>/site/ are publicly mounted there. Templates, manifests, and partials stay private to the shared renderer.

Available template helpers:

• asset
• link
• external
• mailto
• tel
• price
• nonEmpty

Intent

This contract lets PlatformKit shapeshift per business without pushing demo-specific design code into the shared module layer.