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 10 with the Windows Subsystem for Linux installed
• macOS 10.13 or greater
• Ubuntu Linux 18.x or greater

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.

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.

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:

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.

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.

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:

• Go to http://localhost:3000/

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.

Now that your local development environment is set up, the next step is to push a code bundle to Managed Runtime and deploy it using Runtime Admin. When you can access Runtime Admin, you’re ready to complete the last guide in the Get Started series: Push and Deploy Bundles.