@swell/storefront-app-sdk-core

@swell/storefront-app-sdk-core

Framework-agnostic core for the Swell Storefront App SDK. Handles template state management, editor communication, visual overlays, translations, and storefront data.

Note: Most apps should install @swell/storefront-app-sdk-react instead. This package is installed automatically as its dependency. Use this package directly only if you're building a custom framework adapter.

Architecture

StorefrontApp (orchestrator)
├── TemplateEngine        — Immer-based state for sections, blocks, settings
│   ├── MessageBus        — postMessage protocol (editor ↔ preview)
│   ├── ColorSchemeManager — CSS custom property generation
│   ├── TranslationManager — t() function, locale switching
│   └── EditorOverlayManager — visual selection/hover overlays
├── UniversalRenderer     — builds ComponentDescriptor tree from state
├── ComponentRegistry     — schema metadata storage
└── Storefront            — swell-js wrapper (menus, locales, currencies)

Building a Framework Adapter

A framework adapter creates a StorefrontApp, subscribes to snapshots, and renders the descriptor tree using framework-specific components.

import {
  StorefrontApp,
  type AppSnapshot,
  type ComponentDescriptor,
  type ComponentRegistration,
  type ThemeData,
} from "@swell/storefront-app-sdk-core";

// 1. Create the app
const app = new StorefrontApp({
  themeData: { header, content, footer, settings, schemas, locales },
  components: [
    { type: "section:hero_banner", schema: heroBannerSchema },
    { type: "block:button" },
  ],
});

// 2. Subscribe to state changes
app.subscribe((snapshot: AppSnapshot) => {
  // snapshot.descriptor  — ComponentDescriptor tree to render
  // snapshot.storefrontData — menus, locales, currencies, ready flag
  renderToFramework(snapshot);
});

// 3. Start loading storefront data (menus, locales, etc.)
const cancel = app.start();

// 4. After DOM update, notify the editor
app.notifyPageLoaded();

// 5. Cleanup
app.destroy();

StorefrontApp API

constructor(options: StorefrontAppOptions)

interface StorefrontAppOptions {
  themeData: ThemeData;              // Template data (regions, settings, schemas)
  components: ComponentRegistration[]; // Registered component types + schemas
  debug?: boolean;                   // Enable debug logging
}

start(): () => void

Starts async storefront loading (menus, locales, currencies). Returns a cancel function.

subscribe(listener: (snapshot: AppSnapshot) => void): () => void

Subscribe to snapshot changes. Called when template state or storefront data changes. Returns unsubscribe function.

getSnapshot(): AppSnapshot

Returns current snapshot synchronously.

interface AppSnapshot {
  descriptor: ComponentDescriptor;   // Tree of components to render
  storefrontData: StorefrontData;    // Storefront runtime data
}

notifyPageLoaded(): void

Call after the framework has committed the descriptor to the DOM. Sends PAGE_LOADED to the editor so it can update overlays.

getStorefront(): Storefront

Access the Storefront instance for setLocale(code) / setCurrency(code).

destroy(): void

Cleanup all subscriptions, event listeners, and DOM elements (overlays).

ComponentDescriptor

The descriptor tree produced by UniversalRenderer:

interface ComponentDescriptor {
  type: string;           // "section:hero_banner", "block:button", or "__root__"
  id: string;             // Instance ID
  props: Record<string, unknown>; // Resolved settings (with locale overrides applied)
  children?: ComponentDescriptor[];
}

The adapter walks this tree and maps each type to a framework component.

Editor Integration

The SDK handles editor communication automatically:

• SET_THEME_DATA — editor sends updated template data → state updates → new snapshot
• SET_EDITOR_STATE — editor sends selection/hover state → overlay updates
• OVERLAY_HOVER / OVERLAY_SELECT / OVERLAY_ADD_CLICK — SDK sends user interactions back to editor
• PAGE_READY / PAGE_LOADED — SDK notifies editor of render lifecycle

Components must render data-section-id / data-block-id attributes for overlays to work:

<section data-section-id="abc123">...</section>
<div data-block-id="xyz789">...</div>

Exported Types

// Theme data
SectionGroup, SectionConfig, BlockConfig,
ThemeSettings, ThemeData,
ComponentSchema, ComponentSchemas,
SchemaField, SchemaFieldType,
SettingsGroup, SettingsSchema,

// Storefront runtime
StorefrontData, Locale, Currency,
Menu, MenuItem, ResolvedMenu, ResolvedMenuItem,
LocaleData, LocalesMap,

// App orchestration
StorefrontApp, StorefrontAppOptions,
AppSnapshot, ComponentDescriptor, ComponentRegistration,

// Values
swell,  // swell-js client instance
t,      // translation function