Development Environment Setup

Set up your local development environment for building Commerce Apps.

Prerequisites

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

Claude Code Skills

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

Skill	Description
`/scaffold-app`	Generate a complete app directory structure with templates
`/package-app`	Package an app into a registry-ready ZIP
`/validate-app`	Comprehensive validation (structure, manifest, SHA256, IMPEX)
`/validate-impex`	Deep IMPEX validation for syntax and common errors
`/generate-service-impex`	Generate service credential, profile, and definition IMPEX
`/generate-site-preferences-impex`	Generate site preference IMPEX
`/generate-custom-object-impex`	Generate custom object type IMPEX
`/extract-app`	Extract a commerce app ZIP for development or modification
`/diff-versions`	Compare two app versions for changelogs
`/submit-pr`	Guide through the PR submission process

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.

CLI Authentication Setup

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.

OCAPI Configuration

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.

WebDAV Access

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.

CLI Commands

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

b2c cap validate

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.

1b2c cap validate <path>

Examples:

1# Validate a CAP directory
2b2c cap validate ./commerce-avalara-tax-app-v0.2.5
3
4# Validate a packaged CAP zip
5b2c cap validate ./commerce-avalara-tax-app-v0.2.5.zip

b2c cap package

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

1b2c cap package <path> [--output, -o <dir-or-file>] [--json]

Examples:

1# Package to the current directory
2b2c cap package ./commerce-avalara-tax-app-v0.2.5
3
4# Package to a specific output directory
5b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist
6
7# Package to a specific filename
8b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip

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

b2c cap install

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.

1b2c cap install <path> --site-id <site-id> [--clean-archive] [--timeout <seconds>] [--skip-validate] [--json]

Flags:

Flag	Description
`--site-id`, `-s`	(Required) Site ID to install the Commerce App on. Alias: `--site`
`--clean-archive`	Delete the uploaded zip from the instance after install. By default the archive is kept on the instance.
`--timeout`, `-t`	Timeout in seconds for the installation job
`--skip-validate`	Skip CAP structure validation before install
`--json`	Output results as JSON

Examples:

1# Install from a directory
2b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch
3
4# Install from a zip file
5b2c cap install ./commerce-avalara-tax-app-v0.2.5.zip --site-id RefArch
6
7# Install and skip pre-validation
8b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate
9
10# Install and clean up the archive from the instance afterward
11b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive

b2c cap uninstall

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.

1b2c cap uninstall <app-id> --site-id <site-id> [--timeout <seconds>] [--json]

Flags:

Flag	Description
`--site-id`, `-s`	(Required) Site ID to uninstall the Commerce App from. Alias: `--site`
`--timeout`, `-t`	Timeout in seconds for the uninstall job
`--json`	Output results as JSON

Examples:

1b2c cap uninstall avalara-tax --site-id RefArch

b2c cap list

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.

1b2c cap list [--local] [--site-id <site-id>[,<site-id>]] [--timeout <seconds>] [--json]

Flags:

Flag	Description
`--local`, `-l`	List Commerce Apps found in local directories instead of querying a remote instance
`--site-id`, `-s`	Site ID(s) to query. Accepts comma-separated values for multiple sites. Alias: `--site`
`--timeout`, `-t`	Timeout in seconds for the remote query
`--json`	Output results as JSON

Examples:

1# List apps installed on a remote instance
2b2c cap list --site-id RefArch
3
4# List apps across multiple sites
5b2c cap list --site-id RefArch,SiteGenesis
6
7# List locally available Commerce App directories
8b2c cap list --local

b2c cap tasks

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.

1b2c cap tasks <app-name> --site-id <site-id> [--timeout <seconds>] [--json]

Flags:

Flag	Description
`--site-id`, `-s`	(Required) Site ID where the app is installed. Alias: `--site`
`--timeout`, `-t`	Timeout in seconds for the remote query
`--json`	Output results as JSON

Examples:

1# View configuration tasks for an installed app
2b2c cap tasks avalara-tax --site-id RefArch

b2c cap pull

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.

1b2c cap pull [app-name] [--site-id <site-id>] [--output, -o <dir>] [--timeout <seconds>] [--json]

Flags:

Flag	Description
`--site-id`, `-s`	Site ID to query for installed apps. Alias: `--site`
`--output`, `-o`	Output directory for downloaded packages. Default: `./commerce-apps`
`--timeout`, `-t`	Timeout in seconds for the download
`--json`	Output results as JSON

Examples:

1# Pull a specific app
2b2c cap pull avalara-tax --site-id RefArch
3
4# Pull all installed registry apps to a custom directory
5b2c cap pull --site-id RefArch --output ./downloaded-apps

End-to-End Development Lifecycle (ISV and SI)

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:

Stage	Goal	Primary tooling
Scaffold	Generate a CAP directory structure and starter manifests	`/scaffold-app`, `/generate-service-impex`, `/generate-site-preferences-impex`, `/generate-custom-object-impex`
Develop	Implement cartridge hooks, Storefront Next extensions, and IMPEX	Your editor + cartridge dev tooling; `/validate-impex` for incremental IMPEX checks
Test	Validate, package, install on a sandbox, and exercise end-to-end	`b2c cap validate`, `b2c cap package`, `b2c cap install`, `b2c cap tasks`, `b2c cap list`
Submit/Ship	Diff against the previous version, publish to the registry (ISV) or hand off to the merchant (SI)	`/diff-versions`, `/submit-pr`, `b2c cap pull` for parity checks

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.

Inner Development Loop (Test Stage)

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

Develop your code locally (cartridges, scripts, Storefront Next extensions)
Organize your project into the CAP directory structure (see CAP Structure)
Validate your CAP structure:
1b2c cap validate ./my-commerce-app

Package into a .zip file:

1b2c cap package ./my-commerce-app --output ./dist

Install on your sandbox (the CLI handles the WebDAV upload and job execution automatically):
1b2c cap install ./dist/my-commerce-app-v1.0.0.zip --site-id RefArch
View and complete configuration tasks:
1b2c cap tasks my-commerce-app --site-id RefArch
Follow the Business Manager links provided to configure service credentials and site preferences.
Test end-to-end on your sandbox storefront
Verify installation status:
1b2c cap list --site-id RefArch
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:
1b2c cap install ./my-commerce-app --site-id RefArch

Iterating Across Sandbox Environments

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.

Inspecting Installed App State

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.

CI/CD Pipeline Integration

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:

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.
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.
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.
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.

Feature Toggles and Prerequisites

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.

Troubleshooting Development Issues

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.