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

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

• 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

LLM-ready docs

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

Glossary

• Instant Site: Website builder created by Ecwid. Read more: Help Center.

• 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

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

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

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
design	Design editor definitions	Design Editors
layout	Layout configurations and design overrides	Layout
showcase	Showcase configurations	Showcases
template	Template configuration and page definitions	Templates
section	Section references in pages (default, custom, store)	Templates — Pages
translation	Translation settings	Translations

The content and design factories also provide content.default.*() and design.default.*() sub-factories for creating standalone default values used in showcases.

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