> 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/getting-started/make-your-first-template.md).

# Make your first template

Templates define the page layouts for your store. A template ties together your custom sections with a header, footer, and page configurations.

In this tutorial, you'll create a template that uses the hero banner section from [Make your first section](/site-themes/develop-site-themes/getting-started/make-your-first-section.md) on the home page.

### Scaffold the Template

```bash
npx @lightspeed/crane@latest init --template my-store
```

This creates the following structure inside `templates/my-store/`:

```
templates/my-store/
├── configuration.ts     # Template metadata, header, and footer
└── pages/
    ├── home.ts          # Home page layout
    ├── catalog.ts       # Catalog page layout
    ├── category.ts      # Category page layout
    ├── custom.ts        # Custom page layout
    └── product.ts       # Product page layout
```

### Template Configuration

Edit `templates/my-store/configuration.ts` to define the template metadata:

```typescript
// templates/my-store/configuration.ts
export default {
  metadata: {
    name: 'My Store Template',
    description: 'A custom template featuring a hero banner on the home page.',
    preview_url: 'https://my-store.company.site/',
    cover_image: {
      set: {
        ORIGINAL: {
           url: 'reference_template_cover_image.jpeg',
        },
      },
    },
  },
  header: {
    type: 'default',
    id: 'header',
  },
  footer: {
    type: 'default',
    id: 'footer',
  },
};
```

The `cover_image` URL references an image in `templates/assets/`.

### Add the Section to a Page

Edit `templates/my-store/pages/home.ts` to place the hero banner on the home page:

```typescript
// templates/my-store/pages/home.ts
import { template, section } from '@lightspeed/crane-api';

export default template.page({
  sections: [
    section.custom({
      id: 'hero-banner',
      showcase_id: '1',
    }),
  ],
});
```

Each section entry has:

* **`type`** — set automatically by the factory function. There are three section types:
  * `'custom'` — your own sections from `sections/`
  * `'default'` — pre-defined Lightspeed sections (slider, cover, etc.). See the default sections reference for the full list.
  * `'store'` — a storefront page placeholder, used exclusively on storefront pages (`product.ts`, `catalog.ts`, `category.ts`)
* **`id`** — the section folder name (e.g., `hero-banner` matches `sections/hero-banner/`)
* **`showcase_id`** — which showcase to use as the default content (matches the `showcaseId` in your showcase file)

#### Storefront Pages

Storefront pages (`product.ts`, `catalog.ts`, `category.ts`) **must** contain exactly one section of type `store`. 

These pages are managed by the platform and only accept a `store` section placeholder:

```typescript
// templates/my-store/pages/catalog.ts
import { template, section } from '@lightspeed/crane-api';

export default template.page({
  sections: [
    section.store(),
  ],
});
```

{% hint style="info" %}
**Page Types**

The `home.ts` and any custom pages accept `custom` and `default` sections. Storefront pages (`product.ts`, `catalog.ts`, `category.ts`) accept only `store` sections. See Pages for full details.
{% endhint %}

### Build and Preview

Build your application and start the preview server:

```bash
npx @lightspeed/crane@latest build
npx @lightspeed/crane@latest preview
```

Open the preview URL in your browser. You should see your hero banner section rendered with the showcase content on the home page.

{% hint style="info" icon="book-open" %}
**Want to know more about Crane CLI commands?**

Jump into [Deep dive into Crane CLI](/site-themes/develop-site-themes/getting-started/deep-dive-into-crane-cli.md)
{% endhint %}

### Next steps <a href="#next-steps" id="next-steps"></a>

You now know how to create a template and wire sections into pages. To go deeper:

* [Deep dive into Crane CLI](/site-themes/develop-site-themes/getting-started/deep-dive-into-crane-cli.md) — full command reference, workflow examples, and troubleshooting
* [Templates](/site-themes/develop-site-themes/templates.md) — full template documentation
* [Pages](/site-themes/develop-site-themes/templates/pages.md) — page types, section types, and validation rules


---

# 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/getting-started/make-your-first-template.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.