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:

In v2, the method being used to create the Express server has been changed. The createApp method has been deprecated and replaced with a method called getRuntime.

The getRuntime method returns a runtime object. You can use the createHandler method to create Managed Runtime compatible lambda handlers. The second argument is a callback function that gives you access to the Express app, allowing you to customize the Express app. For example you can use the callback function to implement custom endpoints.

In v2, body-parser library is removed from the express app. If you have custom endpoints that requires req.body parsed and populated, install the body-parser library by running npm install body-parser and include the body parser library in ssr.js:

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.