Configuration

Every template requires a configuration.ts file at its root. This file defines the template's metadata, page chrome (header and footer), and can define optional global visual defaults (colors, fonts, alignment, page layout, and corner radius).

Full example

typescript

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',
  }),
  styleId: 'customName-001',
  globalSettings: {
    colorPalette: {
      colorA: '#111111',
      colorB: '#FFFFFF',
      colorC: '#F5F5F5',
      colorD: '#D9D9D9',
      colorE: '#666666',
      colorF: '#FF5A00',
    },
    fonts: {
      fontPair: {
        headingFont: 'inter',
        headingFontStyle: 'bold',
        bodyFont: 'roboto',
        bodyFontStyle: 'regular',
      },
      general: {
        heading1: { fontSize: 48 },
        heading2: { fontSize: 40 },
        heading3: { fontSize: 32 },
        heading4: { fontSize: 24 },
        body1: { fontSize: 20 },
        body2: { fontSize: 18 },
        body3: { fontSize: 16 },
        body4: { fontSize: 14 },
      },
    },
    alignment: 'center',
    pageLayout: {
      contentWidth: 1128,
    },
    cornerRadius: 'sharp',
  },
});

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 required `metadata`, `header`, and `footer`, plus optional all-or-none `styleId` and `globalSettings`.
`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 required top-level properties. Style settings are optional, but if you use them, provide both styleId and a complete globalSettings object. Delete both properties when the template does not define style settings; do not leave globalSettings: {} in configuration.ts.

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
`styleId`	No	Style identifier for the template's theme. Required when `globalSettings` is provided. Generated templates set this to `customName-001`
`globalSettings`	No	Global design defaults for colors, typography, layout, and shape. Required when `styleId` is provided

`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)

ℹ️ Note

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.

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)

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)

`styleId`

The optional style identifier for the template's theme. Generated templates set it to customName-001. If you provide styleId, you must also provide a complete globalSettings object.

`globalSettings`

Optionally defines global design values that can be reused by template pages and sections. If the template does not need style settings, delete the globalSettings object from configuration.ts instead of leaving it empty.

Property	Required	Description
`colorPalette`	Yes	Six-color global palette (`colorA`-`colorF`)
`fonts`	Yes	Typography system (font pair + font sizes)
`alignment`	Yes	Default content alignment. One of: `left`, `center`
`pageLayout`	Yes	Default page layout settings
`cornerRadius`	Yes	Required default corner radius token

`globalSettings.colorPalette`

colorPalette must contain exactly six hex colors.

Property	Required	Description
`colorA`	Yes	Hex color, e.g. `#111111`
`colorB`	Yes	Hex color, e.g. `#FFFFFF`
`colorC`	Yes	Hex color
`colorD`	Yes	Hex color
`colorE`	Yes	Hex color
`colorF`	Yes	Hex color

`globalSettings.fonts`

fonts contains a base font pair and default sizes for typography tokens.

Property	Required	Description
`fontPair`	Yes	Base heading/body font family and style
`general`	Yes	Default font sizes for `heading1`-`heading4` and `body1`-`body4`

`globalSettings.fonts.fontPair`

Property	Required	Description
`headingFont`	Yes	Font family. Allowed values are validated by Crane's built-in font enum lists (system, Google, and custom set).
`headingFontStyle`	Yes	One of: `regular`, `medium`, `semibold`, `bold`, `regular-italic`, `medium-italic`, `semibold-italic`, `bold-italic`
`bodyFont`	Yes	Font family. Same allowed set as `headingFont`
`bodyFontStyle`	Yes	One of: `regular`, `medium`, `semibold`, `bold`, `regular-italic`, `medium-italic`, `semibold-italic`, `bold-italic`

`globalSettings.fonts.general`

Each token (heading1, heading2, heading3, heading4, body1, body2, body3, body4) requires a fontSize value.

Allowed fontSize values are:

12, 14, 16, 18, 20, 24, 32, 36, 40, 48, 56, 64, 80, 96, 112.

`globalSettings.alignment`

Required default alignment for theme content when globalSettings is provided. Allowed values are left and center.

`globalSettings.pageLayout`

Required default page layout settings when globalSettings is provided.

Property	Required	Description
`contentWidth`	Yes	Content width as an integer, e.g. `1128`

`globalSettings.cornerRadius`

Required default corner radius token. Allowed values are:

sharp, softened, slightly_rounded, rounded, greatly_rounded.

WARNING

globalSettings is optional as a whole. However, if you keep it in configuration.ts, all of its fields are mandatory. globalSettings: {} and partially filled style settings fail validation during crane build.

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

Style Settings Errors

Error	Cause	Resolution
`globalSettings is required when styleId is provided`	`styleId` is set without `globalSettings`	Add a complete `globalSettings` object or remove `styleId`
`styleId is required when globalSettings is provided`	`globalSettings` is set without `styleId`	Add `styleId` or remove `globalSettings`
Required field errors under `globalSettings`	`globalSettings` is empty or incomplete	Fill all style fields or delete `globalSettings` from the config

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

Global Settings Errors

Error	Cause	Resolution
`Invalid enum value`	Unsupported `headingFontStyle` / `bodyFontStyle`	Use one of `regular`, `medium`, `semibold`, `bold`, `regular-italic`, `medium-italic`, `semibold-italic`, `bold-italic`
`Invalid input`	Unsupported font family name	Use a font value from Crane's supported font lists
`Invalid input: expected one of ...`	Unsupported `fontSize` value	Use one of the allowed font size tokens listed in this guide
`must be a valid hex color` / `Invalid string`	Invalid `colorPalette` hex value	Use valid hex color format, for example `#1A1A1A`
`Invalid option` / `Invalid input`	Unsupported `alignment` or `cornerRadius` value	Use one of the documented theme values
`Invalid input: expected int`	`pageLayout.contentWidth` is not an integer	Use an integer content width, for example `1128`

⚠️ Strict Mode

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

Templates

Layouts

Sections

Settings

UI Helpers

Configuration

Factory Functions

Properties

`metadata`

`metadata.cover_image`

`metadata.preview_url`

`metadata.categories`

`header`

Default Header Section

Custom Header Section

`footer`

Default Footer Section

Custom Footer Section

`styleId`

`globalSettings`

`globalSettings.colorPalette`

`globalSettings.fonts`

`globalSettings.fonts.fontPair`

`globalSettings.fonts.general`

`globalSettings.alignment`

`globalSettings.pageLayout`

`globalSettings.cornerRadius`

Validation Errors

Metadata Errors

Style Settings Errors

Image Errors

Section Errors

Schema Errors

Global Settings Errors

Next Steps

Layouts

Settings

UI Helpers

Configuration ​

Factory Functions ​

Properties ​

metadata ​

metadata.cover_image ​

metadata.preview_url ​

metadata.categories ​

header ​

Default Header Section ​

Custom Header Section ​

footer ​

Default Footer Section ​

Custom Footer Section ​

styleId ​

globalSettings ​

globalSettings.colorPalette ​

globalSettings.fonts ​

globalSettings.fonts.fontPair ​

globalSettings.fonts.general ​

globalSettings.alignment ​

globalSettings.pageLayout ​

globalSettings.cornerRadius ​

Validation Errors ​

Metadata Errors ​

Style Settings Errors ​

Image Errors ​

Section Errors ​

Schema Errors ​

Global Settings Errors ​

Next Steps ​

Configuration

Factory Functions

Properties

`metadata`

`metadata.cover_image`

`metadata.preview_url`

`metadata.categories`

`header`

Default Header Section

Custom Header Section

`footer`

Default Footer Section

Custom Footer Section

`styleId`

`globalSettings`

`globalSettings.colorPalette`

`globalSettings.fonts`

`globalSettings.fonts.fontPair`

`globalSettings.fonts.general`

`globalSettings.alignment`

`globalSettings.pageLayout`

`globalSettings.cornerRadius`

Validation Errors

Metadata Errors

Style Settings Errors

Image Errors

Section Errors

Schema Errors

Global Settings Errors

Next Steps