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.
Upgrading doesn’t automatically add any new storefront features from the Retail React App template, but you can manually add them using the latest Retail React App code as a reference.
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).
If you haven’t generated a PWA Kit project yet, see the Quick Start guide to generate a new project using v2.
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
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
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
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.backup.js and incorporate your customizations
Use the following code block as a guide to incorporating your customizations:
Always use the CommonJS module syntax (
ssr.js and in any files imported by
getConfig is used, import it from the new
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 14.17+.
To test whether your changes have been made successfully, run the following commands:
npm startto verify that the app is able to run locally.
npm run buildfor verifying that the build process is successful.
npm run push(and deploy via Runtime Admin) to verify that deploying a bundle is successful.