Configuration

Every template requires a configuration.ts file at its root. This file defines the template's metadata, header/footer sections, and global design settings (colors, typography, alignment, layout, and corner radius).

Full code example:

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

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 metadata, header, and footer, plus optional all-or-none styleId and globalSettings 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)

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.

globalSettings is optional as a whole. However, if you keep it in configuration.ts, all of its fields are mandatory. globalSettings: {} with 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.