Agent Skill · Salesforce Commerce Cloud

sfnext-deployment

Build and deploy Storefront Next storefronts to Managed Runtime (MRT) using the sfnext CLI. Use when running production builds, pushing bundles to MRT with sfnext push, configuring deployment environments, or deploying Page Designer cartridges. This is for Storefront Next deployment — for general MRT management via b2c CLI, see b2c-cli:b2c-mrt.

View SKILL.md on GitHub → Source repository Provider profile
Provider: Salesforce Commerce Cloud Path in repo: skills/storefront-next/skills/sfnext-deployment/SKILL.md

Skill body

Deployment Skill

This skill covers building and deploying Storefront Next storefronts to Managed Runtime (MRT).

Overview

Storefront Next storefronts are deployed to MRT as bundles. The sfnext CLI handles building and pushing bundles, while environment configuration is managed through MRT environment variables.

Production Build

# Build for production
pnpm build

# The build output goes to build/ directory

The production build:

Deploying to MRT

Using sfnext CLI

# Push the current build to MRT
pnpm push

# Push with a specific message
pnpm sfnext push -m "Release v1.2.0"

# Push to a specific environment
pnpm sfnext push --environment staging --wait

Deployment Flow

pnpm build → pnpm push → MRT receives bundle → Deployed to environment

See MRT Deployment Reference for detailed deployment options.

Environment Configuration

Environment variables for MRT are configured through:

  1. MRT Dashboard — Set PUBLIC__ variables per environment (baked into the app at build time)
  2. CLI flags or MRT_* environment variables — Control push/deploy targets
  3. .env files — Local development only (not deployed)

MRT Deployment Variables

# Project slug (required for push)
MRT_PROJECT=my-project-slug

# Target environment (optional — if omitted, bundle is uploaded but not deployed)
MRT_TARGET=development

Application Variables (set in MRT Dashboard)

PUBLIC__app__commerce__api__clientId=prod-client-id
PUBLIC__app__commerce__api__organizationId=prod-org-id
PUBLIC__app__commerce__api__shortCode=prod-short-code

Page Designer Cartridge Deployment

Page Designer metadata must be deployed separately to Commerce Cloud (not MRT):

# Generate cartridge metadata
pnpm generate:cartridge

# Deploy cartridge to B2C instance
pnpm deploy:cartridge

# Deploy with clean (removes old cartridge first)
pnpm deploy:cartridge:clean

# Validate cartridge structure
pnpm validate:cartridge

Cartridge metadata is also auto-generated as part of pnpm build.

Pre-Deployment Checklist

  1. Run tests — pnpm test
  2. Check bundle size — pnpm bundlesize:test
  3. Verify environment variables — All required vars set in target environment
  4. Build successfully — pnpm build completes without errors
  5. Verify SCAPI credentials — Client ID and org ID match the target environment

Troubleshooting

Issue Cause Solution
Build fails TypeScript errors Fix type errors; run pnpm typecheck
Push rejected Authentication issue Verify sfnext CLI credentials
500 errors after deploy Missing environment variables Check all required vars in MRT dashboard
Stale Page Designer components Cartridge not deployed Re-deploy cartridge via MCP tool or b2c CLI

Reference Documentation