Upgrading a scaffolded PWA Studio project

When working with PWA Studio you have two ways to set up your project:

Clone the repository
Use the scaffold command yarn create @magento/pwa to create your starting project

When using 1. getting the latest code base is usually just a git pull / merge away. However with 2. this is not as straight forward. Essentially when using a create command, as is common in the React world, you create a snapshot of the project at the time you run the command and future updates are your responsibility to integrate.

If for example you started in August 2020 you would have created a project based on PWA Studio 7. PWA Studio 7 files

Before running any yarn install the folder content would resemble the package content of venia-concept here. However this is not 100% accurate as some additional processing is run from the source to what gets published via npm - see the buildpack script here.

create-pwa Downsides

The major downside to using the create-pwa approach is that once a new version of PWA Studio gets released how to know what to update? The main areas are:

Package Updates

How do we know for example that PWA Studio 7 ships @magento/venia-ui at version 4.0.0 and version 5.0.0 for PWA Studio 8? At the same time the apollo client was updated from version 2.x to 3.x And this is not a one off either as, for example, PWA Studio 9 includes the jump to React 17.

Webpack config changes

The main webpack.config.js is also a file that is in your project. Over the time I have been tracking this project there have been various changes and improvements made to this file.

Service Worker improvements

The service worker which is set up via the code under src/ServiceWorker is also not set in stone and has seen a number of changes.

create-pwa always uses the latest versions

To my knowledge it is not possible to instruct yarn to use a different version for the create command to essentially go back in time to easily create a diff between the resulting files.

Lots of diffing

In summary the above issues lead to a few headaches when trying to track the upstream PWA Studio project to benefit from the improvements made since you started. If you tried to reconstruct the history of individual files from the source repository I think this becomes unmanageable.

The solution

To be able to create a proper diff between versions for projects started with create-pwa is to re-run the same packaging command the PWA Studio team uses to create the final package. This is exactly what I have done in our PWA Studio Starter repository for the PWA Studio releases since version 7.

You can check the changes in the below links here:

or if you are starting a new project you can also clone the repository directly (we also create a weekly package if you would like to track the upstream progress more closely).