Set Up Your Local Environment

This guide covers how to set up your local environment for developing with PWA Kit.

We recommend using a Unix-based operating system for PWA Kit development, such as:

Windows users: See Microsoft’s official recommendations for Node developers.

You must install specific versions of Node and Node Package Manager (NPM) that are supported by Managed Runtime.

Go to the Node 18.x download page to download the right installer for your machine.

Windows users: Download the .msi file that corresponds to your processor. For example, if you have a 64-bit Intel processor, you would choose the x64 installer.

Mac users: Download the .pkg file.

Apple silicon users: If you haven’t installed Rosetta already, run softwareupdate --install-rosetta.

Linux users: Download the -linux file that corresponds to your processor. For example, if you have a 64-bit Intel processor, you would choose the linux-x64 installer in your preferred archive format.

Now that you’ve downloaded the appropriate Node installer, open it and complete the setup instructions.

When prompted by the installer, accept the default option to also install the Node.js runtime, install Node Package Manager, and add the Node.js runtime to your path.

Before moving on, check that the correct versions of Node and NPM are installed:

  1. Open a terminal.
  2. Run node -v.
  3. Make sure that it returns v18.16.1 (or the latest 18.x version).
  4. Run npm -v.
  5. Make sure that it returns 9.5.1 (or the latest version included with Node 18.x).

If you have a different version of NPM installed, you can install version 9.5.1 manually like this:

  1. Open a terminal.
  2. Run npm install -g npm@9.5.1.
  3. Run npm -v again.
  4. Make sure that it returns 9.5.1.

If you want to manage multiple versions of Node on Windows, we recommend Node Version Switcher or Volta. We don’t recommend Corey Butler’s Node Version Manager (NVM) for Windows because we have encountered issues with it during our testing.

For Mac and Linux users, we recommend installing Node Version Manager.

Every PWA Kit storefront must have a project created in Runtime Admin for managing deployments.

Before you can use Managed Runtime and Runtime Admin, they must be enabled and you must request access to them. To enable Managed Runtime and Runtime Admin for your organization, reach out to your Salesforce account team. For access, ask your Commerce Cloud administrator to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

If you or someone on your team hasn’t already, here’s how to create a project in Runtime Admin:

  1. Log in to Runtime Admin.
  2. Click New Project.
  3. Enter a name for the project.
  4. Click Create Project.

Make a note of the project ID because you need it for generating project files for development.

When you first create a project, the site isn’t accessible on the web until after the necessary cloud infrastructure is deployed. The deployment process can take up to 40 minutes.

To learn more about what you can do in Runtime Admin, see our guide to Managed Runtime Administration.

Most PWA Kit developers start by cloning a repository containing a previously generated set of project files. (To learn how to generate a new project, skip to the next section.)

After cloning your project repository, you must install package dependencies:

  1. Open a terminal.
  2. Change to the project directory.
  3. Run npm ci

If you already have an existing PWA Kit project and have completed the instructions in the last section, you can skip to the next section. Otherwise, you must generate a project.

To generate a project, open a terminal and run the following command. Replace ~/PLACEHOLDER-PROJECT-ID with a path that includes the project ID from Runtime Admin:

In the npx command, you can replace @latest with a specific version of the Retail React App, such as @v3.0.0 or @v2.7.3. If you don’t specify a version, you can get unexpected results due to caching of old versions.

When prompted to choose a project preset, select from one of the following options:

  • retail-react-app-demo: Use the Retail React App storefront template and use the demo sandbox for the back end. No further configuration required.
  • retail-react-app: Use the Retail React App storefront template and use your own B2C Commerce instance for the back end. You must provide configuration values.

When using the retail-react-app preset, the generator script asks you to provide several configuration values. These configuration values associate your new PWA Kit project with a corresponding project in the Runtime Admin tool and a B2C Commerce instance.

The following table provides more information about each project configuration value and where to find them. The configuration values are also covered in more detail in the B2C Commerce API documentation. See Base URL and Request Formation.

Configuration ValueMore Information
Project ID in Managed Runtime AdminManaged Runtime Administration covers how to create a project and look up the project ID of an existing project.
  • Example: example-project
URL for your B2C Commerce instanceNeed a new B2C Commerce instance for development or testing? See Create an On-Demand Sandbox.
  • Example: https://zzdc-001.dx.commercecloud.salesforce.com
Commerce API client IDThis identifier isn’t found in Account Manager anymore. See Generate a Client ID for API Access.
  • Example: 1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
Commerce API private client modeThis toggles whether your application will use a public or private authentication flow for logging in shoppers. See the Shopper Login documentation and Use A SLAS Private Client for more information.
  • Default: true
Site ID in Business ManagerString used to identify a particular ecommerce site. To get a list of available sites and their associated site IDs in Business Manager, go to Administration > Sites > Manage Sites.
  • Example: RefArch
Commerce API organization ID in Business ManagerString used to identify your organization for API access based on the realm and instance. To find the organization ID in Business Manager, go to Administration > Site Development > Salesforce Commerce API Settings.
  • Example: f_ecom_zzdc_001
Commerce API short code in Business ManagerAn eight-character string assigned to a realm for routing purposes. The short code applies to your entire realm environment, across all instances. (The short code for all on-demand sandboxes is kv7kzm78). To find your short code in Business Manager, go to Administration > Site Development > Salesforce Commerce API Settings.
  • Example: kv7kzm78
API Client ID in the Einstein ConfiguratorSee the Einstein API documentation for Commerce Cloud developers and access the Einstein Configurator directly.

After generating a project, we recommend that you commit the generated project files to a repository and share the repository with your storefront developers.

You can edit a project’s configuration values after a project has been generated too. See Configuration Files for more information.

Don’t forget to update the configuration whenever any of these values change, such as when you customize project files to work with a different B2C Commerce instance.

To start your web server for local development, run the following command from your project directory:

Now that the development server is running, you can open a browser and preview your storefront:

You can stop the development server at any time by using the keyboard shortcut Control+C.

To preview a server-side rendered page, append the ?__server_only query string to the URL you’d like to preview. For example, you can test the server-side rendered version of www.example.com by visiting the URL www.example.com?__server_only.

  • After cloning an existing project and running npm ci or generating a new project, it can take a few minutes before you see any activity in the terminal, so don’t cancel the process until it finishes. Also, anti-virus software (especially on Windows) can cause installations to take much longer than usual.

  • If you get an HTTP 401 error response from the authorize endpoint, there’s a configuration problem with the Shopper Login and API Access Service (SLAS). To correct your SLAS configuration, see the instructions in Set Up API Access.