Skip to content
Alokai CMS — Dev Docs

Layouts

Layouts define the shared header (navigation) and footer for your storefront. They are managed in the CMS under Layouts and applied globally to every page.

How it works

┌──────────────┐     GET /api/v1/layout      ┌──────────────────┐
│  Storefront   │ ──────────────────────────▶  │   CMS Delivery   │
│  Root Layout  │      (via SDK/fetch)         │   API            │
│               │ ◀──────────────────────────  │                  │
│  Wraps ALL    │   { header: [...],           │  Resolves the    │
│  pages with   │     footer: [...] }          │  default layout  │
│  nav/footer   │                              │  for the space   │
└──────────────┘                               └──────────────────┘

Root layout fetch

The storefront’s app/[locale]/layout.tsx fetches the CMS layout via sdk.unifiedAlokaiCms.getPage() on the homepage path. The layout field from the response contains the header and footer component zones.

This wraps every page — product pages, category pages, CMS pages, 404, checkout — with the CMS-managed navigation and footer.

Per-page layout overrides

Individual pages can override the default layout by setting a layout_id in the CMS editor. This is useful for landing pages that need a different navigation style.

Layout in the CMS editor

When editing a layout in the CMS, the preview uses LayoutPreviewWrapper which renders the header/footer zones with a “Page Content Area” placeholder in between. Changes are reflected in real-time via postMessage.

Delivery API

GET /api/v1/layout

Returns just the default layout for a space/environment.

Query params:

  • locale — e.g. en-US (default: en-US)
  • environment — e.g. main (default: main)

Headers:

  • Authorization: Bearer {delivery_token} or Bearer {preview_token}
  • X-Alokai-CMS-Space: {space_id}

Response:

{
  "header": [
    { "component": "AppleNavigation", "id": "...", "props": { ... } }
  ],
  "footer": [
    { "component": "AppleFooter", "id": "...", "props": { ... } }
  ]
}

Layout in page responses

The GET /api/v1/pages/by-path/* endpoint includes a layout field alongside the page content:

{
  "componentsAboveFold": [...],
  "componentsBelowFold": [...],
  "layout": {
    "header": [...],
    "footer": [...]
  }
}

When a page is not found but a default layout exists, the response includes _notFound: true with the layout:

{
  "_notFound": true,
  "layout": { "header": [...], "footer": [...] }
}

Storefront integration

RenderCmsLayout

The RenderCmsLayout component wraps children with the layout’s header and footer:

import RenderCmsLayout from '@/sf-modules/cms-alokai-cms/components/render-cms-layout';


<RenderCmsLayout layout={layout}>
  {children}
</RenderCmsLayout>

It normalizes raw CMS component data (flattens props, resolves styles) before passing to RenderCmsContent.

CMS not-found handling

When connectCmsPage receives a _notFound response with layout data, it renders CmsNotFound which displays a 404 message wrapped in the CMS layout.