Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 28 ยท First Steps

Setting Up Your Development Environment

Set up a Salesforce Commerce Cloud development environment: on-demand sandbox, VS Code, dw.json, sfcc-ci, uploading cartridges, activating code and the SFRA npm build.

With most web frameworks you run the application on your laptop. With B2C Commerce you cannot: the runtime only exists on Salesforce's servers. So a development environment here means three things: a sandbox (your own instance in the cloud), a local editor with your cartridge source code, and tooling that uploads your files to the sandbox so you can see changes in the storefront.

This lesson walks through that loop. It builds on the map from What Is Salesforce B2C Commerce?. Once the loop works, the rest of the track is writing code and watching it run.

The commands and configuration below are read-only: they need your own Salesforce realm and credentials. The runnable examples at the end are stand-ins that model a dw.json validator and an upload planner in plain JavaScript. They are not the real tools. Tool names and options change over time, so confirm the current ones in Salesforce's developer documentation before relying on an exact flag.

The development loop

flowchart LR
    A["Edit cartridge<br/>in VS Code"] --> B["Build assets<br/>(npm run compile)"]
    B --> C["Upload changed files<br/>to the sandbox (WebDAV)"]
    C --> D["Reload storefront<br/>and read logs"]
    D --> A

Every change travels from your editor to the sandbox before you can see it run.

The upload step is what makes this different from local development. Uploading a single changed file is fast, but a full re-upload of every cartridge is slow, so tools track what changed.

Getting a sandbox

A sandbox is an instance reserved for development. Your organization's administrators create on-demand sandboxes for you, either in the Account Manager / Business Manager administration tools or with a command line tool. An on-demand sandbox has a time to live (you choose a duration, and it is deleted afterwards unless extended), so treat it as disposable: keep everything that matters in version control, not in the sandbox.

A typical new sandbox is empty or comes with sample data depending on how it was created. You will usually:

  1. Open Business Manager on the sandbox with the account you were given.
  2. Import the site data your project provides (site, catalog, prices, preferences) through Administration > Site Development > Site Import & Export.
  3. Upload code and activate it.
  4. Set the cartridge path for the site (next lesson: Cartridges and the Cartridge Path).

Editor and extensions

Any editor works because you only edit text files, but VS Code is the common choice. Useful extensions:

  • Prophet Debugger (community): uploads files on save, and offers a debugger and log viewing using the platform's debug interface.
  • Salesforce Commerce Cloud tooling by Salesforce (the official extensions): code snippets, ISML support and upload features.
  • An ISML syntax highlighter, and ESLint with the SFRA configuration so style errors show up as you type.

Whatever you install, they all read the same small config file.

The dw.json file

Many tools (including Prophet and the SFRA build scripts) read a dw.json file in your project root. It holds the sandbox address and the code version to upload to:

JSON
{
  "hostname": "zzzz-001.dx.commercecloud.salesforce.com",
  "username": "[email protected]",
  "password": "YOUR-ACCESS-KEY-NOT-YOUR-LOGIN-PASSWORD",
  "code-version": "feature-badges"
}

Key points:

  • hostname is the host only: no https:// and no path.
  • username and password: use an access key or the credential type your tool documents rather than your personal login password, and add dw.json to .gitignore. A committed secret is a security incident.
  • code-version is the name of the folder the files go into on the instance. Many developers use a branch or ticket name.

Some tools also read OAuth client settings for the newer APIs. Check the tool's documentation for the keys it expects.

Uploading code and activating a version

Code is stored on the instance in code versions, each a folder containing your cartridges. The files travel over WebDAV, so the path looks like this:

TEXT
/on/demandware.servlet/webdav/Sites/Cartridges/<code-version>/<cartridge>/cartridge/<files>

Only one code version is active at a time. Uploading to an inactive version does not change what shoppers see; activating a version switches the whole site over at once. That makes releases and rollbacks simple: upload v44, activate it, and if something is wrong, activate v43 again.

You can activate a version in Business Manager under Administration > Site Development > Code Deployment, or from the command line.

The sfcc-ci command line tool

sfcc-ci is a command line client that talks to the platform's APIs. It is widely used in CI pipelines. A typical sequence (read-only, your values will differ):

Terminal
# Read-only: authenticate an API client, then deploy and activate code
sfcc-ci client:auth <client-id> <client-secret>
sfcc-ci code:deploy build/site_cartridges.zip --instance zzzz-001.dx.commercecloud.salesforce.com --code-version v44
sfcc-ci code:activate v44 --instance zzzz-001.dx.commercecloud.salesforce.com
sfcc-ci sandbox:list

The client ID and secret come from an API client you create in Account Manager. Newer Salesforce command line tooling for B2C Commerce also exists; the ideas (authenticate, upload a code version, activate it) are the same.

Building SFRA assets

SFRA stores its JavaScript and CSS source in the cartridge's client folder and compiles it into static files that browsers load. A project based on the reference architecture ships npm scripts for this (read-only):

Terminal
# Read-only: run in the project root
npm install
npm run compile:js
npm run compile:scss
npm run lint
npm run upload      # push changed files using dw.json

The names come from the SFRA project's package.json, so open yours and read the scripts section instead of trusting this list. Remember the split: the npm build happens on your machine (compiled files are uploaded), while server-side controllers, models and ISML are uploaded as they are and run on the platform.

Reading logs

When code misbehaves, the platform's log files are your debugger. On a sandbox, open Administration > Site Development > Development Setup and follow the Log Files link (or open the WebDAV Logs folder). Look at the error- and customerror- files first. Testing, Debugging and Logging goes deeper.

A stand-in dw.json validator

This stand-in checks a config object against rules you could enforce in a project script or a pre-commit hook. The rules are our own, not the platform's.

JS A dw.json validator (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A stand-in upload planner

Tools avoid re-uploading everything by comparing file fingerprints. This stand-in compares a previous manifest with the current files and builds the WebDAV targets for the changes.

JS Which files need uploading? (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can't you run a B2C Commerce storefront entirely on your own laptop?

    The server-side runtime is hosted. Your editor holds the source and tooling uploads it to a sandbox instance.
  2. 2. What does activating a code version do?

    Only one version is active at a time. Uploading to another version is safe; activation is the switch.
  3. 3. Which is a safe practice for dw.json?

    dw.json holds credentials, so it must not be committed. Hostname is a bare host name.
  4. 4. Which part of an SFRA project is built on your machine before upload?

    Client assets are compiled locally. Controllers, models and ISML are uploaded as source and run on the platform.

Summary

  • Development means a cloud sandbox plus local source code and upload tooling.
  • dw.json stores the sandbox host, credentials and code version; never commit it.
  • Code goes into named versions over WebDAV, and activating a version switches the site to it.
  • sfcc-ci and similar tools automate authentication, deployment and activation in CI.
  • SFRA compiles client JS and SCSS locally; server-side files are uploaded unchanged. Read the logs when something fails.

Next: Cartridges and the Cartridge Path