Skip to content

storefront-next.md

Latest commit

 

History

History
217 lines (157 loc) · 8.87 KB

storefront-next.md

File metadata and controls

217 lines (157 loc) · 8.87 KB
description Set up Storefront Next development environments using the B2C CLI to create sandboxes, SLAS clients, MRT environments, and deploy.

Storefront Next

::: warning Important Storefront Next is currently in a closed pilot. Access to Storefront Next is limited to pilot customers. Features and configuration may change. :::

Set up Storefront Next development environments using the B2C CLI to create sandboxes, SLAS clients, MRT environments, and deploy.

Prerequisites

  • B2C CLI installed or use npx @salesforce/b2c-cli to run commands without installing
  • Commerce Cloud realm access
  • A Storefront Next project
  • Appropriate Account Manager roles (detailed per step below)

Step 1: Create an On-Demand Sandbox (Optional)

If you need a new sandbox instance for development, create one with the CLI.

Required Role: Sandbox API User (see Authentication Setup)

b2c sandbox create --realm <REALM> --wait

Note the hostname from the output — you'll need it for later configuration.

After creating a sandbox, you'll need to create or import sites. You can import SFRA in Business Manager under Administration > Site Development > Site Import & Export.

See Sandbox Commands for more options.

Step 2: Create a SLAS Client

Create a SLAS client for your storefront to handle shopper authentication.

Required Role: SLAS Organization Administrator with a tenant filter matching your tenant.

Your tenant ID is found in Business Manager under Administration > Site Development > Salesforce Commerce API Settings. It is the organization ID without the f_ecom_ prefix — for example, if your organization ID is f_ecom_abcd_001, your tenant ID is abcd_001. You can pass either form to the --tenant-id flag and the CLI will handle it.

b2c slas client create \
  --tenant-id <TENANT_ID> \
  --channels <SITE_ID> \
  --redirect-uri "http://localhost:5173,https://*.exp-delivery.com/callback" \
  --default-scopes

The client is created as a private client by default (no --public flag needed).

::: warning Save the client ID and secret from the output — the secret is only shown once and cannot be retrieved later. :::

See SLAS Commands for more options.

Step 3: Create an MRT Environment

Set up a Managed Runtime environment to host your storefront.

Prerequisites:

::: tip Configure your API key in ~/.mobify, dw.json, or via the MRT_API_KEY environment variable so you don't need to pass it on every command. See Configuration for all available options. :::

Find your short code in Business Manager under Administration > Salesforce Commerce API Settings.

b2c mrt env create <SLUG> \
  --project <PROJECT> \
  --name "<NAME>" \
  --allow-cookies \
  --proxy "api=<SHORT_CODE>.api.commercecloud.salesforce.com" \
  --wait

Connect the B2C Commerce Instance

After creating the environment, link it to your B2C Commerce instance by setting the tenant and site IDs:

b2c mrt env b2c -p <PROJECT> -e <ENVIRONMENT> \
  --instance-id <TENANT_ID> \
  --sites <SITE_ID>

See MRT Commands for more options.

Step 4: Set Environment Variables

Configure your MRT environment with the required Storefront Next variables.

Your organization ID and short code are found in Business Manager under Administration > Site Development > Salesforce Commerce API Settings. The organization ID has the form f_ecom_abcd_001.

b2c mrt env var set \
  PUBLIC__app__commerce__api__clientId=<SLAS_CLIENT_ID> \
  PUBLIC__app__commerce__api__organizationId=<ORG_ID> \
  PUBLIC__app__commerce__api__siteId=<SITE_ID> \
  PUBLIC__app__commerce__api__shortCode=<SHORT_CODE> \
  PUBLIC__app__commerce__api__proxy=/mobify/proxy/api \
  PUBLIC__app__commerce__api__callback=/callback \
  PUBLIC__app__commerce__api__privateKeyEnabled=true \
  PUBLIC__app__defaultSiteId=<SITE_ID> \
  PUBLIC__app__i18n__fallbackLng="en-US" \
  PUBLIC__app__i18n__supportedLngs='["en-US"]' \
  PUBLIC__app__commerce__sites='[{"id": "<SITE_ID>", "defaultLocale": "en-US", "defaultCurrency": "USD", "supportedLocales": [{"id": "en-US", "preferredCurrency": "USD"}], "supportedCurrencies": ["USD"]}]' \
  COMMERCE_API_SLAS_SECRET=<SLAS_CLIENT_SECRET> \
  -p <PROJECT> -e <ENVIRONMENT>

Variable Reference

Variable Description
PUBLIC__app__commerce__api__clientId SLAS client ID from Step 2
PUBLIC__app__commerce__api__organizationId Commerce Cloud organization ID (e.g., f_ecom_aaaa_prd)
PUBLIC__app__commerce__api__siteId Site ID (e.g., RefArch)
PUBLIC__app__commerce__api__shortCode Short code from Business Manager
PUBLIC__app__commerce__api__proxy Proxy path for API requests
PUBLIC__app__commerce__api__callback OAuth callback path
PUBLIC__app__commerce__api__privateKeyEnabled Must be true for private SLAS clients
PUBLIC__app__defaultSiteId Default site ID for the storefront
PUBLIC__app__i18n__fallbackLng Fallback locale (e.g., en-US)
PUBLIC__app__i18n__supportedLngs JSON array of supported locales (e.g., ["en-US"])
PUBLIC__app__commerce__sites JSON array of site configurations (see below)
COMMERCE_API_SLAS_SECRET SLAS client secret from Step 2

Most of these values match what's in your project's .env file. The privateKeyEnabled variable must be set to true when using a private SLAS client.

::: warning The COMMERCE_API_SLAS_SECRET contains sensitive credentials. Treat it accordingly and avoid committing it to source control. :::

Multi-Site Configuration

The PUBLIC__app__commerce__sites variable defines the sites, locales, and currencies for your storefront. Each site entry includes:

[
  {
    "id": "SiteID",
    "defaultLocale": "en-US",
    "defaultCurrency": "USD",
    "supportedLocales": [
      { "id": "en-US", "preferredCurrency": "USD" }
    ],
    "supportedCurrencies": ["USD"]
  }
]

Add additional objects to the array for multi-site setups.

Step 5: Deploy

Deploy your Storefront Next project from the project directory.

Primary method using the Storefront Next CLI:

pnpm sfnext push --project-slug <PROJECT> --target <ENVIRONMENT>

This is run from your Storefront Next project directory.

Alternative using the B2C CLI directly (builds and deploys):

b2c mrt bundle deploy -p <PROJECT> -e <ENVIRONMENT> \
  --ssr-only '["server/**/*", "loader.js", "sfnext-server-*.mjs", "streamingHandler.{js,mjs,cjs}", "streamingHandler.{js,mjs,cjs}.map", "!static/**/*", "!**/*.stories.tsx", "!**/*.stories.ts", "!**/*-snapshot.tsx", "!.storybook/**/*", "!storybook-static/**/*", "!**/__mocks__/**/*", "!**/__snapshots__/**/*"]' \
  --ssr-shared '["client/**/*", "static/**/*", "**/*.css", "**/*.png", "**/*.jpg", "**/*.jpeg", "**/*.gif", "**/*.svg", "**/*.ico", "**/*.woff", "**/*.woff2", "**/*.ttf", "**/*.eot", "!**/*.stories.tsx", "!**/*.stories.ts", "!**/*-snapshot.tsx", "!.storybook/**/*", "!storybook-static/**/*", "!**/__mocks__/**/*", "!**/__snapshots__/**/*"]'

These patterns match the defaults used by pnpm sfnext push. The --ssr-only and --ssr-shared flags accept either a JSON array (for patterns with brace expansion) or a comma-separated string, and can be overridden if your project structure differs.

Step 6: Debugging with Log Tailing

After deploying, you can tail application logs in real time to debug runtime issues.

# Tail all logs from your environment
b2c mrt tail-logs -p <PROJECT> -e <ENVIRONMENT>

# Show only errors and warnings
b2c mrt tail-logs -p <PROJECT> -e <ENVIRONMENT> --level ERROR --level WARN

# Search for specific patterns
b2c mrt tail-logs -p <PROJECT> -e <ENVIRONMENT> --search "timeout|500"

This is useful for diagnosing deployment failures, SSR errors, and API connectivity issues. See MRT Commands for all options.

Summary

Step Command Required?
1. Create Sandbox b2c sandbox create Optional
2. Create SLAS Client b2c slas client create Yes
3. Create MRT Environment b2c mrt env create Yes
4. Set Environment Variables b2c mrt env var set Yes
5. Deploy pnpm sfnext push or b2c mrt bundle deploy Yes
6. Debug with Log Tailing b2c mrt tail-logs Optional

Next Steps