# Crane overview

To start building Site themes, you must have a clear view of your design system, backend dev environment, and the ability to push your code to Ecwid. To help you on the journey, Ecwid developed the **Crane framework**.

Let's learn what it can do and how you can use it to speed up your development!

### What is Crane <a href="#what-is-crane" id="what-is-crane"></a>

Crane is a specialized framework for building Server-Side Rendered (SSR) e-commerce themes on the Lightspeed Online Presence (E-Series/Ecwid) platform using Vue 3 and Vite.

### Key Features <a href="#key-features" id="key-features"></a>

* **Fast Development**: Quickly scaffold, develop, and preview custom sections with hot module replacement and TypeScript support
* **Fully Customizable**: Build sections with complete control over HTML, CSS, and JavaScript while leveraging powerful APIs
* **Developer Experience**: Built-in TypeScript support, ESLint configurations, and comprehensive tooling for modern web development
* **Headless API Client**: Access Ecwid's public API with a fully-typed, headless JavaScript client for building custom integrations
* **Modern Stack**: Powered by Vite for lightning-fast builds and development experience

{% hint style="success" %}
**LLM-ready docs**

This documentation is fully LLM-ready! Go to <https://docs.ecwid.com/llms-full.txt> and use the <kbd>#Getting started</kbd> tag as the entry point for LLM use of Crane docs.
{% endhint %}

### Glossary <a href="#glossary" id="glossary"></a>

* **Instant Site:** Website builder created by Ecwid. Read more: [**Help Center**](https://support.ecwid.com/hc/en-us/sections/360001694100-Instant-Site).
* **Instant Site Editor:** Native UI for building Ecwid websites.
* **Ecwid admin:** A one-for-all tool, where users can manage all aspects of their store.
* **Theme**: A pre-configured design for the whole website.
* **Template**: A defined store structure and appearance distributable as a deployable theme.
* **Preview store:** Theme draft visible only to the store owner.
* **Custom Application**: Project defining boundaries of custom building blocks for a specific topic.
* **Custom Section**: Essential building block for custom functionality.
* **Default Section**: Existing building block in Lightspeed E-Commerce.
* **Content Settings**: Section configuration for content (titles, buttons, texts).
* **Design Settings**: Section configuration for design (colors, font sizes).
* **Showcase**: Section highlight with specific configuration values.
* **Section layout**: Configuration for elements' placement and arrangement in a section.
* **Storefront**: The storefront is the public-facing part of your e-commerce website where customers can browse products, add them to their cart, and complete transactions.
* **Slot**: A slot is a placeholder for a custom section in a storefront layout.
* **Storefront layout**: The layout of a whole storefront page.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you begin, ensure you have:

* **Node.js**: Version 22.x or higher
* **npm**: Version 10 or higher
* **Lightspeed Application Credentials**: Contact your Partner Manager for:
  * Application client ID and secret key
  * Required permissions for deployment
  * Test site access (optional)

### Packages <a href="#packages" id="packages"></a>

Crane is organised into four packages:

| Package                           | Description                                                                 |
| --------------------------------- | --------------------------------------------------------------------------- |
| `@lightspeed/crane`               | CLI tool for scaffolding, building, previewing, and deploying applications  |
| `@lightspeed/crane-api`           | Runtime library providing Vue 3 composables for content and design settings |
| `@lightspeed/ecom-headless`       | Fully-typed headless JavaScript client for the Ecwid public API             |
| `@lightspeed/eslint-config-crane` | Preconfigured ESLint setup for section development                          |

### Project Structure <a href="#project-structure" id="project-structure"></a>

A typical Crane application structure:

```
my-app/
├── crane.config.json      # Application credentials
├── package.json           # Node.js dependencies
├── sections/              # Custom sections
│   ├── example-section/   # Default example section
│   └── my-section/        # Your custom sections
├── headers/               # Custom header components
│   └── example-header/    # Your custom header
├── footers/               # Custom footer components
│   └── example-footer/    # Your custom footer
├── preview/               # Local development preview server
│   ├── sections/          # Section preview setup
│   ├── shared/            # Shared preview utilities
│   ├── ssr-server.ts      # SSR server for local testing
│   └── vite.config.js     # Vite configuration for preview
├── shared/                # Shared components and utilities
├── dist/                  # Built output (generated)
└── node_modules/          # Dependencies (generated)
```

### Factory Methods <a href="#factory-methods" id="factory-methods"></a>

All configuration objects in Crane are created using factory functions from `@lightspeed/crane-api`. Factories accept a typed config object, auto-inject the `type` discriminator field, and return a fully typed result.

| Factory       | Purpose                                                    | Details                                                                                  |
| ------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `content`     | Content editor definitions                                 | [Content Editors](/site-themes/develop-site-themes/sections/settings/content-editors.md) |
| `design`      | Design editor definitions                                  | [Design Editors](/site-themes/develop-site-themes/sections/settings/design-editors.md)   |
| `layout`      | Layout configurations and design overrides                 | [Layout](/site-themes/develop-site-themes/sections/settings/layout.md)                   |
| `showcase`    | Showcase configurations                                    | [Showcases](/site-themes/develop-site-themes/sections/showcases.md)                      |
| `template`    | Template configuration and page definitions                | [Templates](/site-themes/develop-site-themes/templates.md)                               |
| `section`     | Section references in pages (`default`, `custom`, `store`) | [Templates — Pages](/site-themes/develop-site-themes/templates/pages.md)                 |
| `translation` | Translation settings                                       | [Translations](/site-themes/develop-site-themes/sections/settings/translations.md)       |

The `content` and `design` factories also provide `content.default.*()` and `design.default.*()` sub-factories for creating standalone default values used in [showcases](/site-themes/develop-site-themes/sections/showcases.md).

```typescript
import { content, design, layout, showcase, template, section, translation } from '@lightspeed/crane-api';
```


---

# 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/getting-started/crane-overview.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.