Upgrading to the latest PWA Studio version gives your project access to the new features, bugfixes, and improvements associated with that release. This topic provides general guidance and best practices for upgrading your storefront project to use the newest PWA Studio release.
The contents of this topic applies to storefront projects setup according to the Setup your project tutorial.
These projects use the
venia-concept package as a template to set up the directory structure and project dependencies.
This is the recommended setup for new projects because it makes version upgrades easier.
The main updates you need to make in your storefront project are the dependency versions in your
PWA Studio packages are independently versioned, which means their versions may not be the same as the main PWA Studio release version.
If your project uses
yarn, you can call
yarn add on each of the
This automatically updates the
package.json file in your project and install the latest versions.
yarn add @magento/eslint-config @magento/pagebuilder @magento/peregrine @magento/pwa-buildpack @magento/upward-js @magento/venia-ui
If your project uses
npm, you can still manually edit the
package.json file with the latest published version.
Compare the contents of your project’s
package.json file with the one in
venia-concept to see the latest published versions.
You can find the latest package versions by opening the template project’s
package.json file in GitHub and using the version switcher to view the latest release version under the Tags tab.
For example, the
package.json file for the v10.0.0 release is at:
Use the contents of this file to update the
@magento packages listed in your project’s
npm install to install the updated packages.
Update template files
Updating your dependencies does not update the initial template files in your project. You must identify and apply these changes manually so that they do not conflict with your own changes. Use the instructions in the following sections to update your project’s template files.
Clone PWA Studio
To compare changes between the source template and your project, you need a local clone of the PWA Studio repository. Use the following command to create a local clone:
git clone email@example.com:magento/pwa-studio.git
If you already have a copy of the repository, use the following command to update it with the latest changes:
git fetch origin
Next, checkout the version tag of the recent release. For example, the following command checks out the state of the repository at version 10.0.0:
git checkout v10.0.0
Identify which template files changed
You can use the PWA Studio repository clone to identify which files changed between versions in the
venia-concept template package using
cd packages/venia-concept && \ git diff --name-only --relative v9.0.1..v10.0.0 . ../
This command navigates to the
venia-concept package and uses the
git diff command to list the files changed between the
v10.0.0 version tags:
_buildpack/__tests__/create.spec.js _buildpack/create.js package.json prettier.config.js src/.storybook/preview-body.html src/.storybook/webpack.config.js src/ServiceWorker/Utilities/__tests__/imageCacheHandler.spec.js src/ServiceWorker/Utilities/imageCacheHandler.js src/ServiceWorker/setupWorkbox.js src/registerSW.js template.html webpack.config.js
How you apply updates to the template files in your project depends on whether you made changes to that file or not. If you did not make any changes to your project’s template file, you can safely copy over the file into your project to overwrite and update it.
If your project’s template file contains any customizations, you must manually apply the updates from the new version.
To find the changes you need to apply, you can use the
git diff command on individual files:
For example, the following command shows the updates you would need to make to the
git diff v9.0.1..v10.0.0 webpack.config.js
Check for new environment variables
To check for new or updated environment variables, run a diff on the
envVarDefinitions.json file in the pwa-buildpack package.
For example, the following command shows the updates on that file between versions
git diff v9.0.1...v10.0.0 packages/pwa-buildpack/envVarDefinitions.json
If you need to make updates to your local
env file, you may also need to update the environment variables in your staging and production environments.