Upgrade to v2

Upgrade a project that was generated before v2 of PWA Kit to take advantage of the framework and tooling improvements made in v2.

We’ve added lots of new features to PWA Kit v2, including:

🥳 TypeScript support. The build tools now support TypeScript by default—without having to update the configuration files for Babel or Webpack.

🧰 An updated development server that supports hot reloading on the server side and makes it possible to support hot reloading on the client side in a future release.

🤓 An all-new command-line tool called pwa-kit-dev that bundles our recommended development tools like Webpack, Babel, and Jest to support zero-config project templates.

🖌️ Experimental support for non-React apps for those users interested in using Managed Runtime to host other Express-based apps (not just the Retail React App).

We made the upgrade process from v1.5 to v2 as easy as possible—with changes required to only a small number of existing project files.

If you’re upgrading from v1.4 (or earlier), the process is the same as upgrading from v1.5, but with one extra step. Update all import statements involving pwa-kit-react-sdk so that the import path doesn’t include the dist/ folder anymore.

Read on to complete the remaining upgrade tasks (for both v1.5 and v1.4 users).

To start the upgrade process, open package.json from the root directory of your project.

Add and install three new pwa-kit-* packages:

Remove the following dependencies. The new pwa-kit-dev tool now takes care of these dependencies for you. (If the version numbers don’t exactly match the ones you have in your project, remove them anyway.)

Convert these NPM scripts to use the new pwa-kit-dev:

Open babel.config.js from the root directory of your project and replace the entire file with this one line:

If you have made any customizations to your Babel configuration, add them below the call to the require() function.

If you haven’t customized the webpack.config.js file from the root directory of your project, delete it. A default configuration file is loaded automatically for you.

If you do have customizations, you must add them after calling the require() function first to get the base configuration:

If you have made any customizations to the ssr.js file in the app directory, rename the file to ssr.backup.js so that you can preserve your customizations.

Download the new version of ssr.js from GitHub and copy it to the app directory of your project. If you have no customizations, overwrite the existing file.

If you have customizations, open both ssr.js and ssr.backup.js and incorporate your customizations ssr.backup.js into ssr.js.

Use the following code block as a guide to incorporating your customizations:

Whenever getConfig is used, import it from the new pwa-kit-runtime package:

Open worker/main.js and add this new route:

In v2, the proxy settings for each Managed Runtime environment must be defined explicitly. In v1, there was a fallback mechanism that allowed a Managed Runtime environment to use the same proxy settings as the local development environment. The fallback mechanism is not supported for v2 projects due to performance and maintenance issues.

To learn how to configure proxy settings for Managed Runtime environments using the Runtime Admin tool or the Managed Runtime API, see Proxy Requests.

You can also take advantage of the new environment-specific configurations feature in v2 to configure proxy settings for your Managed Runtime environments.

Before v2, PWA Kit supported Node 12.x. With v2, you must ensure that your code works with Node 16+.

To test whether your changes have been made successfully, run the following commands:

1. npm start to verify that the app is able to run locally.
2. npm run build for verifying that the build process is successful.
3. npm run push (and deploy via Runtime Admin) to verify that deploying a bundle is successful.