Pages

Template pages define which sections appear on each page of your storefront. Every page is a separate .ts file inside the pages/ directory of your template.

my-template/
├── configuration.ts
└── pages/
    ├── home.ts          # HOME page
    ├── product.ts       # PRODUCT storefront page
    ├── catalog.ts       # CATALOG storefront page
    ├── category.ts      # CATEGORY storefront page
    └── about.ts         # CUSTOM page

import { template, section } from '@lightspeed/crane-api';

export default template.page({
  sections: [
    section.default({
      id: 'slider',
      showcase_id: '001',
    }),
    section.custom({
      id: 'hero-banner',
      showcase_id: '1',
    }),
    section.custom({
      id: 'featured-products',
      showcase_id: '1',
    }),
  ],
});

Each page file must default-export the result of the template.page() factory from @lightspeed/crane-api. The file name determines the page type.

Page Types

The file name (without extension) maps to one of the built-in page types. Names that do not match a reserved name are treated as custom pages.

File name	Page type	Description
home.ts	HOME	The storefront home page
product.ts	PRODUCT	Product detail pages (storefront page)
catalog.ts	CATALOG	The product catalog page (storefront page)
category.ts	CATEGORY	Category listing pages (storefront page)
Any other name	CUSTOM	A custom page defined by your template

ℹ️ Storefront pages

PRODUCT, CATALOG, and CATEGORY are storefront pages. They have special constraints — see Validation Errors below.

Factory Functions

The @lightspeed/crane-api package exports the following factory functions used in page files:

Factory	Description
template.page()	Creates a page configuration object with full type safety. Accepts sections and optionally metadata.
section.default()	Creates a default section referencing a pre-defined Lightspeed section. Sets type to 'default' automatically.
section.custom()	Creates a custom section referencing your own section implementation. Sets type to 'custom' automatically.
section.store()	Creates a storefront section placeholder. Sets type to 'store' automatically.

💡 Recommended

Using factory functions is recommended over plain objects. They provide type safety and automatically set the type discriminator field for you.

Properties

The page configuration object has the following properties:

Property	Required	Description
sections	Yes	Array of sections displayed on this page
metadata	Conditional	Required for CUSTOM pages, must be omitted for others

metadata

Only used on custom pages. Provides display information for the page.

Property	Required	Description
title	Yes	Display title of the page (string)

Example — custom page with metadata — click to expand

import { template } from '@lightspeed/crane-api';

export default template.page({
  metadata: {
    title: 'About Us',
  },
  sections: [],
});

sections

An array of section objects. Each section must be one of three types: default, custom, or store.

Default Section

References a pre-defined Lightspeed section.

Property	Required	Description
type	Auto	Set automatically by section.default()
id	Yes	Must match a default section name, optionally suffixed with _XXX where XXX is three digits (string)
showcase_id	No	Three-digit showcase identifier (string)

The available default section IDs are:

ID	Description
header	Site header
footer	Site footer
cover	Cover image / hero banner
announcement_bar	Announcement bar
slider	Image slider / carousel
special_offer	Special offer / promotion
customer_review	Customer reviews
company_info	Company information
shipping_payment	Shipping and payment info
location	Store location / map
store	Store product listing
video	Video embed
image_gallery	Image gallery
contact_info	Contact information
contacts_widget_whatsapp	WhatsApp contact widget
contacts_widget_instagram	Instagram contact widget
contacts_widget_facebook	Facebook contact widget
contacts_widget_phone	Phone contact widget

To use multiple instances of the same default section, append _XXX (three digits) to the ID, e.g., slider_001, slider_002.

💡 Discoverability

Use your editor's autocompletion on the id field of section.default() to discover all valid values.

Custom Section

References one of your own section implementations.

Property	Required	Description
type	Auto	Set automatically by section.custom()
id	Yes	Identifier matching a section in your sections/ directory (string)
showcase_id	No	Showcase identifier (string)
showcase_overrides	No	Override showcase content and design values (object)
category	No	Category for collection sections (string)

Store Section

A placeholder for storefront-managed content. Used exclusively on storefront pages.

Property	Required	Description
type	Auto	Set automatically by section.store()
id	No	Optional identifier (string)

Example — storefront page — click to expand

import { template, section } from '@lightspeed/crane-api';

export default template.page({
  sections: [
    section.store(),
  ],
});

Validation Errors

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

Storefront Page Errors

Storefront pages (PRODUCT, CATALOG, CATEGORY) follow strict rules: the sections array must contain exactly one section of type store.

Error	Cause	Resolution
sections must contain at least one section	sections array is empty on a storefront page	Add a section.store() entry
Page type "..." must have exactly one section	Storefront page has more than one section	Keep only one section.store() entry
Page type "..." must have a section of type "store"	Storefront page section is not of type store	Replace the section with section.store()

Non-Storefront Page Errors

Non-storefront pages (HOME, CUSTOM) cannot contain store sections and must not use 'header' or 'footer' as section ids (those belong in configuration.ts).

Error	Cause	Resolution
Page type "..." cannot contain store sections	Non-storefront page contains a store section	Remove the store section or move it to a storefront page
Section "header" or "footer" is not allowed among page sections	A section uses 'header' or 'footer' as its id	Move header/footer sections to configuration.ts

Metadata Errors

CUSTOM pages must include a metadata property with a title. All other page types must not include metadata.

Error	Cause	Resolution
Page type "CUSTOM" must have a metadata property	Custom page is missing metadata	Add a metadata object with a title
Page type "..." must not have a metadata property	Non-custom page includes metadata	Remove the metadata property

Section Errors

Error	Cause	Resolution
Custom section with id "..." must exist in sections directory	Referenced custom section not found	Create the matching section in the sections/ directory
id must match pattern: [default_section_name] or [default_section_name]_XXX	Default section id doesn't follow the naming convention	Use a valid default section name, optionally suffixed with _ and three digits
showcase_id must be a three digit string	showcase_id is not three digits	Use a three-digit string like '001'

Schema Errors

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

⚠️ Strict Mode

The page schema uses strict mode. Only documented properties are allowed — any extra fields will cause a validation error.

Next Steps

• Learn about template configuration
• Explore layouts and slots