# Set Up Your Local Environment This guide covers how to set up your local environment for developing with PWA Kit. ## Recommendations We recommend using a Unix-based operating system for PWA Kit development, such as: - Windows 10 with the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl) installed - macOS 10.13 or greater - Ubuntu Linux 18.x or greater **Windows users**: See Microsoft’s [official recommendations](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows) for Node developers. ## Required Software 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](https://nodejs.org/dist/latest-v22.x/) 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. ### Run the Node Installer 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. ### Check the Versions of Node and NPM 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 `v22.14.0` (or the latest `22.x` version). 4. Run `npm -v`. 5. Make sure that it returns `9.5.1` (or the latest version included with Node `22.x`). ### Install NPM Manually 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`. ### Multiple Versions of Node If you want to manage multiple versions of Node on Windows, we recommend [Node Version Switcher](https://github.com/jasongin/nvs) or [Volta](https://volta.sh/). 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](https://github.com/nvm-sh/nvm). ## Create a Runtime Admin Project Every PWA Kit storefront must have a project created in [Runtime Admin](https://runtime.commercecloud.com/) for managing deployments. :::important 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**. ::: 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](https://runtime.commercecloud.com). 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. :::note 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](/docs/commerce/b2c-commerce/guide/managed-runtime-administration.md). ## Use Existing Project Files 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` ## Generate New Project Files 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: ```bash npx @salesforce/pwa-kit-create-app@latest --outputDir ~/PLACEHOLDER-PROJECT-ID ``` :::note 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. ::: ### Project Presets When prompted to choose a project preset, select from one of the following options: - `retail-react-app-demo`: Use the [Retail React App](/docs/commerce/b2c-commerce/guide/retail-react-app.md) storefront template and use the demo sandbox for the back end. No further configuration required. - `retail-react-app`: Use the [Retail React App](/docs/commerce/b2c-commerce/guide/retail-react-app.md) storefront template and use your own B2C Commerce instance for the back end. You must provide configuration values. ### 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](/docs/commerce/b2c-commerce/guide/base-url.md). | Configuration Value | More Information | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Project ID in Managed Runtime Admin | [Managed Runtime Administration](/docs/commerce/b2c-commerce/guide/managed-runtime-administration.md) 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](/docs/commerce/b2c-commerce/guide/creating-an-on-demand-sandbox.md). | | Commerce API client ID | This identifier isn’t found in Account Manager anymore. See [Generate a Client ID for API Access](/docs/commerce/b2c-commerce/guide/setting-up-api-access.md#3-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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.md#slas-clients) and [Use A SLAS Private Client](/docs/commerce/b2c-commerce/guide/use-a-slas-private-client.md) 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 ![App Launcher](https://a.sfdcstatic.com/developer-website/sfdocs/commerce-cloud/media/shared/appLauncher.png) 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 ![App Launcher](https://a.sfdcstatic.com/developer-website/sfdocs/commerce-cloud/media/shared/appLauncher.png) 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 ![App Launcher](https://a.sfdcstatic.com/developer-website/sfdocs/commerce-cloud/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Salesforce Commerce API Settings**. | | API Client ID in the Einstein Configurator | See the [Einstein API documentation](https://developer.salesforce.com/docs/commerce/einstein-api/overview) for B2C Commerce developers and access the [Einstein Configurator](https://configurator.cquotient.com/) 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](/docs/commerce/b2c-commerce/guide/configuration-options.md) for more information. :::note 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. ::: ## Start Your Web Server To start your web server for local development, run the following command from your project directory: ```bash npm start ``` Now that the development server is running, you can open a browser and preview your storefront: - Go to 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`. ## Troubleshooting - 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](/docs/commerce/b2c-commerce/guide/setting-up-api-access.md). ## See Also - [Build and Customize](/docs/commerce/b2c-commerce/guide/build-customize.md)