Section Collections

Section collections group custom sections into reusable, distributable packages. They bundle multiple sections with metadata (name, description, cover image) so they can be offered as a set in the Instant Site Editor.

Creating a Collection

Use the CLI to scaffold a new collection:

crane init --collection <name>

This creates the directory structure under collections/. The command fails if a collection with that name already exists.

Folder Structure

collections/
├── assets/                          # Shared assets (cover images)
│   └── collection_cover_image.png
└── <collection-name>/
    └── configuration.ts             # Collection descriptor

Configuration

The configuration.ts file defines the collection's metadata and the sections it includes.

Factory Functions

The @lightspeed/crane-api package exports the following factory functions used in configuration files:

Factory	Description
collection.configuration()	Creates a collection configuration object with full type safety. Accepts metadata, and sections properties.
section.custom()	Creates a custom section referencing your own section implementation. Sets type to 'custom' automatically.

Properties

Metadata Properties

Property	Type	Required	Description
metadata.name	string	Yes	Display name (2–60 characters)
metadata.description	string	Yes	Description text (2–150 characters)
metadata.cover_image	ImageData	Yes	Cover image with set containing at least one resolution
metadata.preview_url	string	No	Preview URL for the collection
metadata.categories	string[]	No	Template categories (unique values, see below)

Template Categories

Available values for metadata.categories:

• apparel_footwear

• vape_smoke

• home_garden

• sport_outdoor

• jewelry_accessories

• pet_animals

• bikes

• health_beauty

• gift_shop

• electronics

• other

Sections

The sections array defines which custom sections are included in the collection. Each entry references a section from your sections/ directory.

Section Properties

Property	Type	Required	Description
type	'custom'	Yes	Always 'custom'
id	string	Yes	Section ID (must exist in the sections/ directory)
showcase_id	string	No	Default showcase to use
showcase_overrides	object	No	Override showcase defaults (see Showcases — Showcase Overrides)
category	string	No	Section category for classification in the editor

Section Categories

Available values for the category field:

COVER, ANNOUNCEMENT, STORE, SLIDER, VIDEO, SPECIAL_OFFER, CUSTOMER_REVIEW, COMPANY_INFO, SHIPPING_PAYMENT, LOCATION, COLLECTIONS, BRANDS, CONTACT_INFO

Example

// collections/my-collection/configuration.ts
import { collection, section } from '@lightspeed/crane-api';

export default collection.configuration({
  metadata: {
    name: 'Example Collection',
    description: 'Example Collection with custom sections',
    cover_image: {
      set: {
        ORIGINAL: {
          url: 'collection_cover_image.png',
        },
      },
    },
  },
  sections: [
    section.custom({
      type: 'custom',
      id: 'example-section',
      showcase_id: '1',
      category: 'COLLECTIONS',
    }),
  ],
});

Asset Path

The cover_image URL references a file in the collections/assets/ directory.

Build and Deploy

Collections are built and deployed alongside sections and templates — no additional commands needed:

crane build    # Builds sections, templates, and collections
crane deploy   # Deploys everything to the platform