Settings

Settings files define the Editor UI for your section — they control what merchants can customize through the Instant Site Editor. Each setting maps to a specific editor widget (text input, image uploader, color picker, toggle, etc.) and specifies its configuration and default values.

Folder Structure

sections/<section-name>/settings/
├── content.ts       # Content editor definitions (required)
├── design.ts        # Design editor definitions (required)
├── layout.ts        # Layout configurations (optional)
└── translations.ts  # Multi-language text for editor labels and defaults (optional)

Core Concepts

Settings as Records

Both content and design settings are defined as Record<string, Editor> objects. The keys you choose become the field identifiers used throughout your section — in composables, showcases, and layout configurations.

// ContentSettings = Record<string, ContentEditor>
// DesignSettings = Record<string, DesignEditor>

Factory Functions

All editors are created using factory functions from @lightspeed/crane-api. These factories auto-inject the correct type discriminant and provide type safety:

import { content, design } from '@lightspeed/crane-api';

Build-Time Validation

Crane validates all settings files at build time. Invalid configurations (missing required fields, type mismatches, invalid default values) produce clear error messages. Relevant validation errors are documented in each sub-page.

Minimal Example

A simple section with a title and background color:

settings/content.ts

import { content } from '@lightspeed/crane-api';

export default {
  title: content.inputbox({
    label: '$label.content.title',
    defaults: { text: '$label.defaults.title' },
  }),
  hero_image: content.image({
    label: '$label.content.hero_image',
  }),
};

settings/design.ts

import { design } from '@lightspeed/crane-api';

export default {
  title_style: design.text({
    label: '$label.design.title_style',
    defaults: { font: 'global.fontFamily.heading', size: 32, bold: true, color: '#000000', visible: true },
  }),
  section_background: design.background({
    label: '$label.design.background',
    defaults: { style: 'COLOR', color: '#FFFFFF' },
  }),
};

Key Mapping

The string keys (title, hero_image, title_style, section_background) are the same identifiers you pass to composables like useInputboxElementContent('title') and useTextElementDesign('title_style').