Your First Template

Templates define the page layouts for your store. A template ties together your custom sections with a header, footer, and page configurations. In this tutorial, you'll create a template that uses the hero banner section from Your First Section on the home page.

Scaffold the Template

npx @lightspeed/crane@latest init --template my-store

This creates the following structure inside templates/my-store/:

templates/my-store/
├── configuration.ts     # Template metadata, header, and footer
└── pages/
    ├── home.ts          # Home page layout
    ├── catalog.ts       # Catalog page layout
    ├── category.ts      # Category page layout
    ├── custom.ts        # Custom page layout
    └── product.ts       # Product page layout

Template Configuration

Edit templates/my-store/configuration.ts to define the template metadata:

// templates/my-store/configuration.ts
export default {
  metadata: {
    name: 'My Store Template',
    description: 'A custom template featuring a hero banner on the home page.',
    preview_url: 'https://my-store.company.site/',
    cover_image: {
      set: {
        ORIGINAL: {
           url: 'reference_template_cover_image.jpeg',
        },
      },
    },
  },
  header: {
    type: 'default',
    id: 'header',
  },
  footer: {
    type: 'default',
    id: 'footer',
  },
};

The cover_image URL references an image in templates/assets/.

Add the Section to a Page

Edit templates/my-store/pages/home.ts to place the hero banner on the home page:

// templates/my-store/pages/home.ts
import { template, section } from '@lightspeed/crane-api';

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

Each section entry has:

• type — set automatically by the factory function. There are three section types:
  • 'custom' — your own sections from sections/
  • 'default' — pre-defined Lightspeed sections (slider, cover, etc.). See the default sections reference for the full list.
  • 'store' — a storefront page placeholder, used exclusively on storefront pages (product.ts, catalog.ts, category.ts)
• id — the section folder name (e.g., hero-banner matches sections/hero-banner/)
• showcase_id — which showcase to use as the default content (matches the showcaseId in your showcase file)

Storefront Pages

Storefront pages (product.ts, catalog.ts, category.ts) must contain exactly one section of type store. These pages are managed by the platform and only accept a store section placeholder:

// templates/my-store/pages/catalog.ts
import { template, section } from '@lightspeed/crane-api';

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

💡 Page Types

The home.ts and any custom pages accept custom and default sections. Storefront pages (product.ts, catalog.ts, category.ts) accept only store sections. See Pages for full details.

Build and Preview

Build your application and start the preview server:

npx @lightspeed/crane@latest build
npx @lightspeed/crane@latest preview

Open the preview URL in your browser. You should see your hero banner section rendered with the showcase content on the home page.

Next Steps

You now know how to create a template and wire sections into pages. To go deeper:

• Templates Guide — full template documentation
• Pages — page types, section types, and validation rules
• CLI Usage — full command reference, workflow examples, and troubleshooting