Sections

Sections are the building blocks of pages — self-contained UI components that define their own content, design, and rendering logic. Merchants interact with sections through the Instant Site Editor, where they can customize content (text, images, buttons) and design (colors, fonts, backgrounds) based on settings you define.

Section Types

Every section has a type that determines where it can be used:

Type	Purpose
SECTION	Standard page section — used within template pages
HEADER	Site header — appears at the top of every page. Has Mandatory Settings
FOOTER	Site footer — appears at the bottom of every page

Headers and footers are structurally identical to sections with a few additional constraints. See Headers and Footers for details.

Folder Structure

Each section lives in its own directory under sections/:

sections/<section-name>/
├── client.ts            # Client-side hydration entry point
├── server.ts            # Server-side rendering entry point
├── Section.vue          # Vue component
├── type.ts              # TypeScript type definitions (Content, Design)
├── settings/
│   ├── content.ts       # Content editor definitions
│   ├── design.ts        # Design editor definitions
│   ├── layout.ts        # Layout configurations (optional)
│   └── translations.ts  # Translation strings (optional)
└── showcases/           # Showcase configurations (optional)
    ├── 1.ts
    ├── 2.ts
    └── translations.ts  # Showcase-specific translations (optional)

Files Overview

Entry Points

• server.ts — Server-side rendering entry point. Uses createVueServerApp to render the section to HTML on the server. See Server

• client.ts — Client-side hydration entry point. Uses createVueClientApp to hydrate the server-rendered HTML in the browser. See Client

Component and Types

• Section.vue — The Vue 3 component that renders the section UI. Uses UI Composables to access content and design data.

• type.ts — TypeScript type definitions using InferContentType and InferDesignType to derive types from your settings files.

Settings

Settings files define what merchants can customize in the Editor. They determine which editors appear (text inputs, image uploaders, color pickers, etc.) and their default values.

• content.ts — Defines content editors (text, images, buttons, etc.)

• design.ts — Defines design editors (colors, fonts, backgrounds, etc.)

• layout.ts — Defines layout variations for the section (optional)

• translations.ts — Multi-language text for editor labels and defaults (optional)

See Settings for full documentation.

Showcases

Showcases define pre-configured variations of a section with specific default content and design values. They appear as selectable presets when merchants add the section to a page.

See Showcases for details.

Mandatory Settings

Sections with type HEADER have mandatory settings that must be present:

Content: menu (type NAVIGATION_MENU) and logo (type LOGO)

Design: logo (type LOGO)

These are enforced at build time. Standard SECTION and FOOTER types have no mandatory settings.

Linting

Crane provides @lightspeed/eslint-config-crane — a preconfigured ESLint setup for section development. The template scaffolds an eslint.config.cjs that consumes it as a one-liner:

// eslint.config.cjs
module.exports = require('@lightspeed/eslint-config-crane');

What It Includes

• Vue 3 — eslint-plugin-vue with recommended rules

• TypeScript — @vue/eslint-config-typescript recommended rules

• Scoped CSS — eslint-plugin-vue-scoped-css recommended rules

• Accessibility — eslint-plugin-vuejs-accessibility

Notable Rules

Rule	Setting	Description
vue/component-api-style	script-setup, composition	Only Composition API with <script setup> allowed
max-len	160	Maximum line length for .ts and .vue files
no-console	warn	Console statements produce warnings
no-debugger	warn	Debugger statements produce warnings

Running the Linter

The template does not include a lint script by default. Run ESLint directly:

npx eslint "./**/*.{js,ts}"

Or add a script to your package.json:

{
  "scripts": {
    "lint": "eslint \"./**/*.{js,ts}\""
  }
}

Advanced Composables

These composables are exported from @lightspeed/crane-api for advanced use cases. Most sections won't need them.

useVueBaseProps

Low-level composable providing reactive access to the full section context:

• context — store and environment information

• content — raw content data

• design — raw design data

• defaults — default values

• site — site configuration (languages, currency, etc.)

• category — current category data (on category pages)

• storeData — store metadata

• globalDesign — global design settings (colors, fonts, text sizes)

• tileId — the section's tile identifier

Use this when the typed content/design composables are not sufficient — for example, when accessing global design tokens directly or reading site-level configuration.

useInstantsiteJsApi

Returns window.instantsite — the platform's JavaScript API for interacting with the storefront runtime (e.g., triggering cart updates, navigation events).

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

const api = useInstantsiteJsApi();

Client-Only

This is a client-only API. Guard usage with typeof window !== 'undefined' or call it inside onMounted. See SSR vs Client-Only Rendering.

Learn more

• Client — Client-side hydration

• Server — Server-side rendering

• Settings — Define content and design editors

• Showcases — Pre-configured section variations

• UI Composables — Access content and design data in Vue components