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 22.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:
node -v.v22.14.0 (or the latest 22.x version).npm -v.9.5.1 (or the latest version included with Node 22.x).If you have a different version of NPM installed, you can install version 9.5.1 manually like this:
npm install -g npm@9.5.1.npm -v again.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, ask your B2C Commerce administrator to add one of these roles to your account in Account Manager: Managed Runtime User or Managed Runtime Admin.
Important
If you or someone on your team hasn’t already, here’s how to create a project in Runtime Admin:
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.
Note
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:
npm ciIf 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:
1npx @salesforce/pwa-kit-create-app@latest --outputDir ~/PLACEHOLDER-PROJECT-IDIn 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.
Note
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 Value | More Information |
|---|---|
| Project ID in Managed Runtime Admin | Managed Runtime Administration covers how to create a project and look up the project ID of an existing project.
|
| URL for your B2C Commerce instance | Need a new B2C Commerce instance for development or testing? See Create an On-Demand Sandbox.
|
| Commerce API client ID | This identifier isn’t found in Account Manager anymore. See Generate a Client ID for API Access.
|
| Commerce API private client mode | This 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.
|
| Site ID in Business Manager | String used to identify a particular ecommerce site. To get a list of available sites and their associated site IDs in Business Manager, click App Launcher  and then select Administration > Sites > Manage Sites.
|
| Commerce API organization ID in Business Manager | String used to identify your organization for API access based on the realm and instance. To find the organization ID in Business Manager, click App Launcher and then select Administration > Site Development > Salesforce Commerce API Settings.
|
| Commerce API short code in Business Manager | An eight-character string assigned to a realm for routing purposes. The short code applies to your entire realm environment, across all instances. To find your short code in Business Manager, click App Launcher and then select Administration > Site Development > Salesforce Commerce API Settings.
|
| API Client ID in the Einstein Configurator | See the Einstein API documentation for B2C Commerce 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.
Note
To start your web server for local development, run the following command from your project directory:
1npm startNow 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.
j