Development Environment Setup

Set up your local development environment for building Commerce Apps.

Before building a Commerce App, ensure you have:

• A Commerce Cloud sandbox instance with Storefront Next enabled
• Access to the Commerce App Registry
• The B2C CLI installed and configured with your instance credentials
• Node.js and npm for Storefront Next development
• A code editor with JavaScript/TypeScript and React support
• Familiarity with Commerce Cloud cartridge development, IMPEX, and the SCAPI/OCAPI model

If you use Claude Code, the Commerce Apps repository provides skills that automate many manual steps:

These skills complement the B2C CLI commands below. Use Claude Code skills for app scaffolding, IMPEX generation, and validation. Use the B2C CLI for installation, uninstallation, and sandbox testing.

The cap install, cap uninstall, cap list (without --local), cap tasks, and cap pull commands require both OCAPI and WebDAV access on your target instance. The cap validate, cap package, and cap list --local commands are local-only and require no authentication.

For full details on B2C CLI authentication, see the B2C CLI Authentication Guide.

Commands that interact with a remote instance (install, uninstall, list, tasks, pull) execute system jobs or query data via the OCAPI Data API. Your API client must grant the standard B2C CLI job-execution permissions on /jobs/*/executions, /jobs/*/executions/*, and /job_execution_search. Configure these in Business Manager under Administration > Site Development > Open Commerce API Settings > Data API.

For the exact JSON resource block, see Required OCAPI Permissions. For broader B2C CLI authentication setup, see the B2C CLI Authentication Guide.

cap install uploads the CAP archive to the instance via WebDAV before triggering the installation job. SCAPI isn’t a substitute for WebDAV upload — there is no SCAPI endpoint that uploads CAP archives. Authenticate WebDAV using one of these methods:

• Business Manager credentials: Set your BM username and WebDAV access key via SFCC_USERNAME and SFCC_PASSWORD environment variables, or use --user-auth to authenticate interactively via the browser.
• Account Manager OAuth client: Configure an OAuth client with WebDAV Client Permissions for the /impex path, in addition to the OCAPI Client Permissions described above. See the B2C CLI WebDAV Access guide for details.

The B2C CLI provides commands for Commerce App development under the cap topic:

Validates your CAP structure, checking manifest integrity, folder structure, and required files. Run this before every packaging step. Accepts a path to a CAP directory or a .zip file.

Examples:

Packages your project directory into a valid .zip CAP file ready for installation or registry submission.

Examples:

Tip: Add --json to any cap command for machine-readable JSON output, useful for scripting and CI pipelines.

Installs a CAP on a target instance. Accepts a local directory or .zip file. The CLI automatically uploads the archive to WebDAV and triggers the server-side installation job. See CLI Authentication Setup for required credentials.

Flags:

Examples:

Uninstalls a Commerce App from a target instance by app ID. The CLI automatically discovers the app’s domain by querying the installed apps on the instance, so you don’t need to specify it.

Flags:

Examples:

Lists Commerce Apps either locally (from the filesystem) or installed on a remote B2C Commerce instance. When querying a remote instance, requires the same authentication as cap install.

Flags:

Examples:

Lists configuration tasks for an installed Commerce App. Tasks include Business Manager deep links for completing post-install configuration such as entering service credentials or setting site preferences.

Flags:

Examples:

Downloads installed Commerce App packages from a B2C Commerce instance to a local directory. If no app name is specified, pulls all registry-sourced apps installed on the instance.

This command is particularly useful for merchants who install Commerce Apps from Business Manager and want to integrate the app’s code into their projects using their existing development workflows, rather than relying on the automated pull request flow. After pulling, the storefront-next/ extensions and cartridges/ from the downloaded package can be reviewed, customized if needed, and integrated into the merchant’s storefront and cartridge projects through their standard source control and deployment processes.

Flags:

Examples:

From the perspective of an ISV building a Commerce App for the registry, or an SI building a private app for a specific merchant, the full lifecycle spans four stages — each backed by a combination of Claude Code skills and B2C CLI commands:

ISVs publish through the Commerce App Registry; SIs typically deliver the CAP directly to the merchant who installs it via Business Manager or b2c cap install. The same packaging, validation, and installation tooling applies in both cases.

Within the Test stage of the lifecycle above, the recommended sandbox iteration loop is:

1. Develop your code locally (cartridges, scripts, Storefront Next extensions)

2. Organize your project into the CAP directory structure (see CAP Structure)

3. Validate your CAP structure:

4. Package into a .zip file:

5. Install on your sandbox (the CLI handles the WebDAV upload and job execution automatically):

6. View and complete configuration tasks:

   Follow the Business Manager links provided to configure service credentials and site preferences.

7. Test end-to-end on your sandbox storefront

8. Verify installation status:

9. Iterate: make changes, re-validate, re-package, re-install

Tip: During rapid development, install directly from the source directory (skipping the separate package step). The CLI packages and uploads for you:

Most ISVs and SIs maintain more than one sandbox: a personal dev sandbox, a shared QA sandbox, and (for ISVs) a partner staging sandbox. The B2C CLI supports per-environment configuration through standard B2C CLI authentication profiles — see the B2C CLI Authentication Guide.

Practical patterns:

• Switch instances by environment variable. Set SFCC_HOSTNAME, SFCC_USERNAME, and SFCC_PASSWORD per shell session (or use a .env loader) to point b2c cap install at a different sandbox without changing your project.
• Reuse the same CAP across environments. Package once, install many times. The same .zip produced by b2c cap package is valid on any compatible sandbox.
• Reset between iterations. Use b2c cap uninstall <app-id> --site-id <site-id> to remove an app cleanly before installing a new build. This exercises your uninstall IMPEX as part of the dev loop.
• Mirror a merchant’s installed state. Use b2c cap pull <app-name> --site-id <site-id> to download exactly what is installed on a target instance, which is useful for reproducing merchant-reported issues locally.

When an installation misbehaves, use the CLI to inspect what the platform actually recorded on the instance:

• List installed apps: b2c cap list --site-id <site-id> returns the apps registered against a site, including their version and lifecycle state. Use --json to pipe into jq for scripted checks.
• View configuration tasks: b2c cap tasks <app-name> --site-id <site-id> returns the merchant task list with deep links to Business Manager. If a task is unexpectedly incomplete, the deep link points directly at the BM page that needs attention.
• Pull the live package: b2c cap pull <app-name> --site-id <site-id> downloads the CAP exactly as the platform unpacked it. Diff the result against your source build.
• Check the job log: Lifecycle errors (INSTALL_FAILED, CONFIGURATION_FAILED, UNINSTALL_FAILED) write detailed step-by-step output to Administration > Operations > Job Schedules in Business Manager.
• Read CommerceFeatureState directly: The system object’s InstallationMetadata JSON field contains the job execution ID, deployed cartridge names, and any error details. See Monitoring and Support.

The cap validate and cap package commands are local-only and require no instance credentials, which makes them well-suited to CI. A typical pipeline:

1. On pull request: Run b2c cap validate <path> --json to fail the build on manifest, structure, or IMPEX errors. Pair with /validate-impex (Claude Code) or your own IMPEX linter for richer feedback.
2. On merge to a release branch: Run b2c cap package <path> --output ./dist --json to produce the release .zip. Capture the file (and its SHA-256) as a build artifact.
3. On promotion to a partner sandbox: Run b2c cap install ./dist/<app>.zip --site-id <site-id> --json against a dedicated CI sandbox using stored SFCC_USERNAME/SFCC_PASSWORD secrets. Follow with b2c cap list --site-id <site-id> --json to confirm the install succeeded. See CLI Authentication Setup for the credential model.
4. On registry publish (ISVs only): Diff against the previous version (/diff-versions) to generate a changelog, then open a PR against the registry that updates the version, zip, and sha256 fields. Do not edit catalog.json manually — registry CI handles version tracking.

Tip: All cap commands accept --json. Prefer JSON output in CI to parse exit codes and structured error messages instead of scraping logs.

The platform automatically manages domain-specific feature toggles during installation — you don’t need to enable them manually. For the per-domain toggle list and uninstall behavior, see Feature Toggles.

Verify that the top-level CommerceAppsEnabled toggle is enabled on your instance. The install and uninstall jobs need this toggle to execute. This toggle is enabled by default on sandboxes provisioned for Commerce Apps development. If your install job returns an error about Commerce Apps not being enabled, contact your administrator.

• Install job returns INSTALL_FAILED: Check the job execution log in Business Manager (Administration > Operations > Job Schedules). Common causes: missing OCAPI permissions, WebDAV access issues, or IMPEX validation errors.
• App appears installed but hooks don’t fire: Verify the site’s cartridge path includes your app’s cartridges. For tax apps, verify TaxAppHooksEnabled is true in the feature toggles. Also confirm that SiteGenesis or SFRA cartridges aren’t on the cartridge path — see Storefront compatibility for details.
• Re-install after code version switch: If you switch the active code version, cartridges may be missing. Re-running the install job re-copies cartridges without re-running IMPEX (idempotency behavior).
• IMPEX placeholder not replaced: Ensure your file extension is one of the supported text types (.xml, .csv, .txt, .json, .properties, .js). Binary files are copied without placeholder replacement.