Getting Started

This guide covers the installation and configuration steps required for developers to get started with PWA Kit.

For a PWA Kit storefront to work correctly, an administrator must first complete the instructions in our guide to Setting Up API Access.

Setting Up Your Environment

Start by making sure that your operating system and hardware are supported.

Supported Operating Systems

  • macOS 10.13 or greater
  • Windows 7 or greater
  • Ubuntu Linux 18.x or greater

We recommend the following hardware, at a minimum:

  • 16 GB of RAM
  • Solid-state drive (SSD)
  • Two or more CPU cores

Installing Node and NPM

To develop with PWA Kit, you must install specific versions of Node and Node Package Manager (NPM) that are supported by the Managed Runtime. We recommend that you use version 14.x, but version 12.x is still supported.

Go to the Node 14.x download page and 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.

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.

Running the 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.

Checking the Versions

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

  1. Open a terminal (or the Command Prompt on Windows)
  2. Run node -v
  3. Make sure that it returns v14.17.0 (or the latest 14.x version)
  4. Run npm -v
  5. Make sure that it returns 6.14.13 (or the latest version included with Node 14.x)

Installing NPM Manually

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

  1. Open a terminal (or the Command Prompt on Windows)
  2. Run npm install -g npm@6.14.13
  3. Run npm -v again
  4. Make sure that it returns 6.14.13

Multiple Versions of Node

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.

Existing Project

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 (or the Command Prompt on Windows).
  2. Change to the project directory.
  3. Run npm ci

New Project

If you already have an existing PWA Kit project and have completed the installation steps above, you can skip to the next section. Otherwise, you must generate a project.

To generate a project, start by opening a terminal (or the Command Prompt on Windows) and run the following command:

The project generator requires several configuration values to associate your new PWA Kit project with a corresponding project on the Managed Runtime and a B2C Commerce instance. The following table shows where to get more information about each value.

Configuration ValueMore Information
Project ID in Managed Runtime AdminThe Managed Runtime Administration guide covers how to create a project and look up the project ID of an existing project.
URL for your Commerce Cloud instanceNeed a new B2C Commerce instance for development or testing? Get help on the B2C Commerce Infocenter: Get Started with On-Demand Sandboxes. A more detailed Trailhead module is also available: Salesforce B2C Commerce On-Demand Sandboxes.
Commerce API client ID in Business ManagerThe Commerce API Configuration Values guide covers how to find this value and Add an API Client covers how to create it.
Commerce API organization ID in Business ManagerThe Commerce API Configuration Values guide covers how to find this value.
Commerce API short code in Business ManagerThe Commerce API Configuration Values guide covers how to find this value.
API Client ID in the Einstein ConfiguratorSee the Einstein documentation for Commerce Cloud developers and access the Einstein Configurator directly.

You can edit these configuration values after a project has been generated too. See Configuration Options for PWA Projects for more information.

Start Your Web Server

To start your web server for local development, run the following command in 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 ?mobify_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?mobify_server_only.

Troubleshooting

  • After 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 error related to the mkdirp package during installation, try installing with Node 12 instead of Node 14. A fix for this issue is coming soon.

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

Next Steps

Now that your local development environment is set up, you’re almost ready to start pushing code to the Managed Runtime.

Before you can push and deploy code bundles to the Managed Runtime, you must request access to the Runtime Admin web application. Contact your Commerce Cloud administrator and ask them to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

When you can access to Runtime Admin, read our guide to Pushing and Deploying Bundles.

To learn more about PWA Kit and Managed Runtime, check out our Architecture Guides and How-To Guides.