Layouts

Storefront layouts define the visual structure of storefront pages — how product, catalog, and category pages arrange their content areas. Each layout is a Vue component that distributes content into named slots.

layouts/
├── product/
│   └── example-product/
│       ├── Main.vue
│       ├── type.ts
│       ├── settings/
│       │   ├── content.ts
│       │   ├── design.ts
│       │   └── translations.ts
│       └── assets/
├── catalog/
│   └── example-catalog/
│       ├── Main.vue
│       ├── type.ts
│       ├── settings/
│       │   ├── content.ts
│       │   └── design.ts
│       └── slots/
│           └── custom-bottom-bar/
│               ├── CustomBottomBar.vue
│               ├── server.ts
│               └── client.ts
└── category/
    └── example-category/
        ├── Main.vue
        ├── type.ts
        └── settings/
            ├── content.ts
            └── design.ts

Each layout directory must be placed under one of the three storefront page directories: product/, catalog/, or category/. A storefront page in your template is linked to a storefront layout — when a template page of type PRODUCT, CATALOG, or CATEGORY is defined, a corresponding layout must exist.

How Layouts Work

A layout is a Vue component (Main.vue) that uses named <slot> elements to define where the storefront places its built-in content areas. Each storefront page type has a predefined set of slot names.

Product layout example:

<template>
  <div>
    <slot :name="Slot.TOP_BAR" />
    <div class="product-main">
      <slot :name="Slot.GALLERY" />
      <slot :name="Slot.SIDEBAR" />
      <slot :name="Slot.DESCRIPTION" />
    </div>
    <slot :name="Slot.REVIEW_LIST" />
    <slot :name="Slot.RELATED_PRODUCTS" />
    <slot :name="Slot.BOTTOM_BAR" />
  </div>
</template>

<script setup lang="ts">
import { ProductLayoutSlot as Slot } from '@lightspeed/crane-api';
</script>

Catalog layout with a custom slot:

<template>
  <div>
    <slot :name="Slot.PRODUCT_LIST" />
    <slot :name="Slot.CUSTOM_SLOT" slot-id="custom-bottom-bar" />
  </div>
</template>

<script setup lang="ts">
import { CatalogLayoutSlot as Slot } from '@lightspeed/crane-api';
</script>

Storefront Pages

Each layout must be placed in a directory matching a storefront page type. The page type determines which slot names are available in the layout component.

Product

Layouts under layouts/product/. Import ProductLayoutSlot from @lightspeed/crane-api.

Slot name	Description
TOP_BAR	Area above the product details
GALLERY	Product image gallery
SIDEBAR	Sidebar alongside the gallery
DESCRIPTION	Product description area
REVIEW_LIST	Customer reviews
RELATED_PRODUCTS	Related product suggestions
BOTTOM_BAR	Area below the product details
CUSTOM_SLOT	Placeholder for a custom slot component

Catalog

Layouts under layouts/catalog/. Import CatalogLayoutSlot from @lightspeed/crane-api.

Slot name	Description
PRODUCT_LIST	Product listing grid or list
BOTTOM_BAR	Area below the product list
CUSTOM_SLOT	Placeholder for a custom slot component

Category

Layouts under layouts/category/. Import CategoryLayoutSlot from @lightspeed/crane-api.

Slot name	Description
CATEGORY_TITLE	Category heading area
PRODUCT_LIST	Product listing grid or list
BOTTOM_BAR	Area below the product list
CUSTOM_SLOT	Placeholder for a custom slot component

Layout Files

Each layout directory can contain the following files:

File	Required	Description
Main.vue	Yes	Vue component defining the layout structure
type.ts	Yes	Type definitions for content and design editors
settings/content.ts	Yes	Content editor settings for the layout
settings/design.ts	Yes	Design editor settings for the layout
settings/translations.ts	No	Translation keys for the layout
assets/	No	Static assets used by the layout (images, icons)
slots/	No	Custom slot components (see Slots)

ℹ️ No server/client entry points

Unlike sections, layouts do not have server.ts or client.ts entry points at their root. Only custom slots within a layout have their own server and client entry points.

The settings/content.ts, settings/design.ts, and settings/translations.ts files use the same editor factories and follow the same conventions as section settings. Refer to the section settings documentation for details:

• Content Editors
• Design Editors
• Translations

Validation Errors

Crane validates your layouts during the build step. Below are the errors you may encounter and how to resolve them.

Layout Errors

Error	Cause	Resolution
Store layout sectionId "..." must be one of: catalog, category, product	Layout is placed in an invalid directory	Move the layout directory under product/, catalog/, or category/
Asset size ... exceeds threshold of ...	A layout asset file exceeds 2 MiB	Reduce the file size or compress the asset
Store section with id "..." and page type "..." must have a corresponding layout defined	A storefront page in your template has no matching layout	Create a layout for the corresponding storefront page type

Schema Errors

Error	Cause	Resolution
Unrecognized key(s) in object	Extra properties in the layout configuration	Remove properties not defined in the schema

⚠️ Asset Size Limit

Each individual layout asset must not exceed 2 MiB. Oversized assets will cause a validation error during the build step.

Next Steps

• Learn about custom slots within layouts
• Learn about template configuration
• Learn about template pages