Configuration

Every template requires a configuration.ts file at its root. This file defines the template's metadata and page chrome (header and footer).

Full code example:

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

export default template.configuration({
  metadata: {
    name: 'My Store Template',
    description: 'A modern template designed for apparel and footwear stores',
    categories: ['apparel_footwear', 'sport_outdoor'],
    preview_url: 'https://my-store-template.company.site',
    cover_image: {
      set: {
        ORIGINAL: {
          url: 'cover_image.jpg',
          width: 1200,
          height: 800,
        },
      },
    },
  },
  header: section.custom({
    id: 'my-custom-header',
    showcase_id: '001',
  }),
  footer: section.default({
    id: 'footer',
  }),
});

The configuration file must default-export the result of the template.configuration() factory from @lightspeed/crane-api.

Factory Functions

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

Factory	Description
template.configuration()	Creates a template configuration object with full type safety. Accepts metadata, header, and footer properties.
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.

Recommended

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

Properties

The configuration object has three top-level properties, all required:

Property	Required	Description
metadata	Yes	Display information shown to store owners
header	Yes	Header section for all pages in the template
footer	Yes	Footer section for all pages in the template

metadata

The metadata object describes how your template appears in the Lightspeed template gallery.

Property	Required	Description
name	Yes	Display name of the template (2–60 characters)
description	Yes	Short description of the template (2–150 characters)
cover_image	Yes	Cover image shown in the template gallery (object)
preview_url	No	URL where the template can be previewed live
categories	No	Array of unique category tags for the template

metadata.cover_image

An object with a required set property and an optional borderInfo property.

Property	Required	Description
set	Yes	Object containing one or more image variants
borderInfo	No	Border metadata for the image (object)

The set object must contain at least one image variant. Available variants:

Variant	Required	Description
ORIGINAL	No	Original full-size image (object)
WEBP_LOW_RES	No	Low-resolution WebP for desktop (object)
WEBP_HI_2X_RES	No	High-resolution 2x WebP for desktop (object)
MOBILE_WEBP_LOW_RES	No	Low-resolution WebP for mobile (object)
MOBILE_WEBP_HI_RES	No	High-resolution WebP for mobile (object)

At least one variant must be present in the set object. Typically you provide ORIGINAL at a minimum.

Each image variant object has:

Property	Required	Description
url	Yes	Path or URL to the image file (string)
width	No	Image width in pixels (non-negative integer)
height	No	Image height in pixels (non-negative integer)

metadata.preview_url

When provided, the preview URL must be a valid URL on an allowed domain. Invalid domains will be rejected during validation.

metadata.categories

An optional array of unique category tags.

Discoverability

The available category values are defined in the factory types. Use your editor's autocompletion on the categories array to discover all valid values.

header

The header section applied to every page in the template. Can be a default section or a custom section.

Default Header Section

Property	Required	Description
type	Auto	Set automatically by section.default()
id	Yes	Must be 'header' or match the pattern header_XXX where XXX is three digits
showcase_id	No	Three-digit showcase identifier (string)

Custom Header Section

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

footer

The footer section applied to every page in the template. Accepts the same structure as header.

Default Footer Section

Property	Required	Description
type	Auto	Set automatically by section.default()
id	Yes	Must be 'footer' or match the pattern footer_XXX where XXX is three digits
showcase_id	No	Three-digit showcase identifier (string)

Custom Footer Section

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

Validation Errors

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

Metadata Errors

Error	Cause	Resolution
name must be at least 2 characters	name is too short	Provide a name with at least 2 characters
name must be at most 60 characters	name is too long	Shorten the name to 60 characters or fewer
description must be at least 2 characters	description is too short	Provide a description with at least 2 characters
description must be at most 150 characters	description is too long	Shorten the description to 150 characters or fewer
preview_url must be a valid URL	Invalid URL format	Use a valid URL starting with http:// or https://
preview_url must match pattern ...	URL is not on an allowed domain	Use an allowed domain for the preview URL
categories must contain unique items	Duplicate values in categories	Remove duplicate category entries

Image Errors

Error	Cause	Resolution
set must have at least one property	cover_image.set is empty	Add at least one image variant (e.g. ORIGINAL)
must be a non-negative integer	Negative width or height value	Use a non-negative integer for image dimensions

Section Errors

Error	Cause	Resolution
Header section must have id "header" when type is "default"	Default header has a non-matching id	Set id to 'header' or use the header_XXX pattern
Footer section must have id "footer" when type is "default"	Default footer has a non-matching id	Set id to 'footer' or use the footer_XXX pattern
Custom header section with id "..." must exist in headers directory	Referenced custom header not found	Create the matching section in the headers/ directory
Custom footer section with id "..." must exist in footers directory	Referenced custom footer not found	Create the matching section in the footers/ 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 configuration	Remove properties not defined in the schema

Strict Mode

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