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 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:
Always use the CommonJS module syntax (require
, module.exports
) in ssr.js
and in any files imported by 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:
npm start
to verify that the app is able to run locally.npm run build
for verifying that the build process is successful.npm run push
(and deploy via Runtime Admin) to verify that deploying a bundle is successful.