> For the complete documentation index, see [llms.txt](https://docs.ecwid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecwid.com/site-themes/develop-site-themes/templates/configuration.md).

# 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:

```typescript
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 <a href="#factory-functions" id="factory-functions"></a>

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.                                                                  |

{% hint style="info" %}
**Recommended**

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

### Properties <a href="#properties" id="properties"></a>

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` <a href="#metadata" id="metadata"></a>

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

{% hint style="info" %}
At least one variant must be present in the `set` object. Typically you provide `ORIGINAL` at a minimum.
{% endhint %}

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.

{% hint style="info" %}
**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.
{% endhint %}

#### `header` <a href="#header" id="header"></a>

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` <a href="#footer" id="footer"></a>

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

{% hint style="warning" %}
`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`.
{% endhint %}

### Validation Errors <a href="#validation-errors" id="validation-errors"></a>

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

#### Metadata Errors <a href="#metadata-errors" id="metadata-errors"></a>

| 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 <a href="#image-errors" id="image-errors"></a>

| 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 <a href="#section-errors" id="section-errors"></a>

| 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 <a href="#schema-errors" id="schema-errors"></a>

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

{% hint style="warning" %}
**Strict Mode**

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/templates/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.