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

```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',
  }),
});
```

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

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

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

{% 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.