@swell/storefront-app-sdk-react

@swell/storefront-app-sdk-react

React adapter for building Swell storefront apps with visual editor support.

Installation

npm install @swell/storefront-app-sdk-react

The core package (@swell/storefront-app-sdk-core) is installed automatically.

Quick Start

import {
  TemplateRenderer,
  type SectionGroup,
  type ComponentSchemas,
} from "@swell/storefront-app-sdk-react";

// Import your section & block components
import { HeroBanner } from "./sections/HeroBanner";
import { Header } from "./sections/Header";
import { Footer } from "./sections/Footer";
import { Button } from "./blocks/Button";

// Import schemas
import heroBannerSchema from "./sections/HeroBanner/schema.json";
import headerSchema from "./sections/Header/schema.json";

const components = {
  sections: { hero_banner: HeroBanner, header: Header, footer: Footer },
  blocks: { button: Button },
};

const schemas: ComponentSchemas = {
  sections: {
    hero_banner: heroBannerSchema,
    header: headerSchema,
  },
  settings: [],
};

function App({ header, content, footer, settings, locales }) {
  return (
    <TemplateRenderer
      header={header}
      content={content}
      footer={footer}
      components={components}
      schemas={schemas}
      settings={settings}
      locales={locales}
    />
  );
}

API

<TemplateRenderer>

Main component that renders the page from theme data.

interface TemplateRendererProps {
  header: SectionGroup;           // Header region (layout, shared across pages)
  content: SectionGroup;          // Page content (varies per page)
  footer: SectionGroup;           // Footer region (layout, shared across pages)
  components: {
    sections: Record<string, React.ComponentType<any>>;
    blocks: Record<string, React.ComponentType<any>>;
  };
  schemas: ComponentSchemas;      // Section schemas for the editor
  settings?: ThemeSettings;       // Global theme settings
  locales?: LocalesMap;           // Locale translation strings
  debug?: boolean;                // Enable debug logging
}

Renders nothing until storefront data is loaded (storefrontData.ready).

setLocale(code: string): Promise<void>

Switch the active locale. Triggers re-render with updated translations and locale-specific setting overrides.

import { setLocale } from "@swell/storefront-app-sdk-react";

await setLocale("de");

setCurrency(code: string): Promise<void>

Switch the active currency.

import { setCurrency } from "@swell/storefront-app-sdk-react";

await setCurrency("EUR");

swell

Re-exported swell-js client instance. Use for API calls (cart, products, account, etc.).

import { swell } from "@swell/storefront-app-sdk-react";

const products = await swell.get("/products", { limit: 10 });
const cart = await swell.cart.get();

t(key: string, params?: Record<string, string>): string

Translation function. Returns the translated string for the active locale.

import { t } from "@swell/storefront-app-sdk-react";

// Simple
t("products.add_to_cart"); // → "Add to cart"

// With interpolation
t("cart.item_count", { count: "3" }); // → "3 items"

Component Props

Section Components

Section components receive their settings as top-level props, plus:

interface SectionProps {
  id: string;                     // Section instance ID
  settings: ThemeSettings;        // Global theme settings
  storefront: StorefrontData;     // Storefront data (menus, locales, currencies)
  children?: React.ReactNode;     // Rendered block components
}

function HeroBanner({ id, heading, subtitle, image, storefront, children }) {
  return (
    <section data-section-id={id}>
      <h1>{heading}</h1>
      <p>{subtitle}</p>
      {children}
    </section>
  );
}

Block Components

Block components receive their settings as top-level props, plus:

interface BlockProps {
  id: string;                     // Block instance ID
  settings: ThemeSettings;        // Global theme settings
  storefront: StorefrontData;     // Storefront data
}

function Button({ id, label, url }) {
  return (
    <div data-block-id={id}>
      <a href={url}>{label}</a>
    </div>
  );
}

Important: Sections must render data-section-id={id} and blocks must render data-block-id={id} on their root element for editor overlay integration.

StorefrontData

Available on every section and block via the storefront prop:

interface StorefrontData {
  menus: Record<string, ResolvedMenu>;  // Navigation menus
  locales: Locale[];                     // Available locales
  locale: string;                        // Active locale code
  currencies: Currency[];                // Available currencies
  currency: string;                      // Active currency code
  ready: boolean;                        // True when storefront data is loaded
}

Types

All types are re-exported from this package — no need to install core separately:

import type {
  // Theme data
  SectionGroup, SectionConfig, BlockConfig,
  ThemeSettings, ComponentSchema, ComponentSchemas,
  SchemaField, SchemaFieldType, SettingsGroup, SettingsSchema,
  // Storefront
  StorefrontData, Locale, Currency,
  Menu, MenuItem, ResolvedMenu, ResolvedMenuItem,
  LocaleData, LocalesMap,
  // Component
  TemplateRendererProps,
} from "@swell/storefront-app-sdk-react";