@salesforce/storefront-next-runtime

Runtime-agnostic libraries for SFCC Storefront Next, providing core functionality for Page Designer integration, SCAPI client generation, and component management.

[!IMPORTANT] Storefront Next is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

Overview

This package provides the foundational runtime libraries for building Salesforce Commerce Cloud (SFCC) Storefront Next applications. It includes:

• Page Designer Integration: Real-time communication APIs and React components for visual editing
• SCAPI Client: Type-safe, auto-generated API clients for Salesforce Commerce APIs

Installation

pnpm add @salesforce/storefront-next-runtime

Requirements

• Node.js >= 24.0.0
• React >= 19.0.0
• React DOM >= 19.0.0

Modules

/design/messaging Page Designer Messaging API

Provides a communication layer between the Page Designer host application and client applications. Enables real-time messaging for design-time interactions, component selection, property updates, and synchronization between the visual editor and the running application.

/design/mode Design Mode Detection

Utilities for detecting and managing the current application mode (Design or Preview). Allows components to conditionally render design-time features and optimize bundle size by excluding design-time code during runtime execution.

/design/react Design-Time React Components

React components and utilities for Page Designer integration. Provides design-time components, type definitions, and runtime utilities. Most components are lazy-loaded from /design/react/core to minimize bundle size, while types and essential runtime components are available directly from this module.

/design/react/core Core React Components

Entry point for React Page Designer integration. Exports only the minimal set of components required for Page Designer functionality to prevent bundling design-time code during runtime when not in design mode. Components from /design/react are dynamically loaded when design mode is active.

/design/styles.css Page Designer Styles

CSS stylesheet containing design layer styles for Page Designer integration. Provides visual overlays, selection indicators, and design-time UI elements. Can be imported and consumed in various ways depending on your bundler configuration and build setup.

/scapi-client SCAPI Client

Type-safe, auto-generated API clients for Salesforce Commerce APIs with operation-based method names.

For detailed technical documentation, architecture details, and update procedures, see SCAPI Client Documentation.

Key Features:

• Type-safe API calls with full TypeScript support
• Intuitive operation names instead of HTTP method + path
• Auto-generated from OpenAPI specifications
• Built on openapi-fetch

Example Usage:

import { createCommerceApiClients } from '@salesforce/storefront-next-runtime/scapi';

// Initialize clients
const clients = createCommerceApiClients({
  baseUrl: 'https://kv7kzm78.api.commercecloud.salesforce.com',
});

// Add authentication middleware
const token = 'your-auth-token';
clients.use({
  onRequest({ request }) {
    request.headers.set('Authorization', `Bearer ${token}`);
    return request;
  },
});

// Call operations using intuitive method names
const response = await clients.shopperProducts.getCategories({
  params: {
    path: {
      organizationId: 'f_ecom_zzrf_001',
    },
    query: {
      ids: ['root'],
      siteId: 'RefArchGlobal',
    },
  }
});

// Fully typed response
console.log(response.data); // CategoryResult type

Generating SCAPI Clients:

pnpm scapi:generate

Development

Build

pnpm build

Development Mode

Watch mode for rapid development:

pnpm dev

Testing

# Type checking
pnpm typecheck

# Run tests
pnpm test

# Run tests with coverage
pnpm test:unit

Linting

# Check for issues
pnpm lint

# Fix issues automatically
pnpm lint:fix

Clean Build Artifacts

pnpm clean

Architecture

Build Configuration

Built using tsdown for optimal bundling:

• Module Format: ESM
• Target: ES2022
• TypeScript: Strict mode enabled
• Output: Type declarations with source maps