Introduction

This article describes the basic steps that need to be taken for a successful PWA migration.

References

• PWA Migrations
• PWA Changelog
• Customization Guide
• Customization Documentation (recent changes made to the Customization Guide)
• Pull Requests
• Guide - 7.10 REST API Changes
• Concept - Headless Application Type - intershop.REST
• Concept - Intershop Progressive Web App - Hybrid Approach
• Hybrid Approach

We Are Running an Older PWA Version. Which Steps Are Necessary to Upgrade to a Newer Version?

The Intershop Progressive Web App is under continuous development. To get an overview of the major changes applied in each version, please visit PWA Migrations.

Additionally, important aspects of the REST API change over time. Please visit Guide - 7.10 REST API Changes for further details.

REST API Changes?

In addition to the PWA, our REST API is also under constant development. Therefore, it is possible that important aspects and endpoints of the REST API may change over time. Please visit Guide - 7.10 REST API Changes for further details. This is especially important if you have customized your REST API and PWA.

How to Update?

Importing changes of new releases is done with Git tooling.

Remember to run npm install after importing a change that modified the package.json and package-lock.json and run tests as well as linting in the process. Additionally, please read the CHANGELOG.md as well as the migrations.md file before migrating.

For further information, please read the Customization Guide and see what has recently changed in this Customization Documentation on GitHub.

Apply Commits / Custom Fixes From a New Release

Intershop provides commits / custom fixes for the latest PWA version via GitHub in the Pull requests section.

Range Cherry-Pick the Commits / Custom Fixes

Follow these steps:

1. Add the Intershop develop repository as a remote repository by running git remote add intershop https://github.com/intershop/intershop-pwa.git.
2. Create a branch based on the main development branch of the current project by running git checkout -b <new_branch_name>.

3. Cherry-pick the desired range of commits of the new Intershop PWA release (e.g by the Intershop PWA version tags or the specific commit SHAs) into the created migration branch by running git cherry-pick <versionTagA>..<versionTagB>.

   Keep in mind that there might be merge conflicts that need to be resolved. It is recommended to use the information and differences for the commits provided in the Intershop GitHub repository.

   Additionally, make sure to run git commit and git cherry-pick --continue after each resolved merge conflict.

4. It is advisable to run npm install again and check if the project's code still works as expected. This can be done, for example, by running npm run check or starting the server.

Rebase the Commits of a New Release

1. Add the Intershop develop repository as a remote repository by running git remote add intershop https://github.com/intershop/intershop-pwa.git.

2. Create a branch based on the release tag of the Intershop PWA  you want to migrate to by running git checkout -b <new_branch_name>.

3. Rebase the commits of the new Intershop PWA release onto the main development branch of the current project by running git rebase --onto <target_branch_name> <commit>. The commit specifies (e.g by the Intershop PWA version tag or the specific commit SHA) where the current migration branch should be "cut off".
   

   Keep in mind that there might be merge conflicts that need to be resolved. It is recommended to use the information and differences for the commits provided in the Intershop GitHub repository.

   Additionally, make sure to run git rebase --continue after each resolved merge conflict.

4. It is advisable to run npm install again and check if the project's code still works as expected. This can be done, for example, by running npm run check or starting the server.

Merge the New Release in Its Entirety

1. Add the Intershop develop repository as a remote repository by running git remote add intershop https://github.com/intershop/intershop-pwa.git.
2. Create a branch based on the main development branch of the current project by running git checkout -b <new_branch_name>.

3. Merge the release branch with the created migration branch by running git merge intershop. 

   Keep in mind that any appearing merge conflicts must be resolved at once without the specific commit context.

4. It is advisable to run npm install again and check if the project's code still works as expected. This can be done, for example, by running npm run check or starting the server.

Is It Necessary to Switch to the New Headless Application Type?

Starting from Intershop Commerce Management 7.10.21.0, the headless application type intershop.REST is available. It is intended to be the application type of choice for headless REST applications for the ICM storefront. The new application type combines B2B and B2C functionality and does not rely on the Responsive Starter Store, but still provides full ICM REST API functionality.

However, it is still possible to use the Responsive Starter Store with the Hybrid Approach. To do so, follow these instructions:

1. Use the latest version of the PWA and revert the commits '50dc72ef0' and '741454c8c'.
2. Additionally, please configure the correct icmApplication setting and add the required PWA-specific content includes in the Responsive Starter Store via componentEntryPointDefinitions in the ICM project source code. 
3. Set up the hybrid configuration.

Please visit Concept - Headless Application Type - intershop.REST as well as Concept - Intershop Progressive Web App - Hybrid Approach for further details.

We Do Not Use Custom Content. How Do We Migrate?

At first, the new intershop.REST application should be created in the appropriate channel. It is also possible to use the B2B or B2C application type. However, this is not recommended, as the PWA is only developed against the new intershop.REST type since version 0.22.

Afterwards, the PWA has to be configured in the environment.default.ts and the environment.model.ts to use that application. The intershop.REST application can be set as default, so no further changes to the icmApplication configuration are required. Any REST API differences in the /customers resource will be compensated by the PWA. However, if multiple applications are running and intershop.REST is not the default application, it should also be set through icmApplication.

[...]
export const ENVIRONMENT_DEFAULTS: Omit<Environment, 'icmChannel'> = {
  	/* INTERSHOP COMMERCE MANAGEMENT REST API CONFIGURATION */
	icmBaseURL: 'https://pwa-ish-demo.test.intershop.com',
  	icmServer: 'INTERSHOP/rest/WFS',
  	icmServerStatic: 'INTERSHOP/static/WFS',
  	icmApplication: 'rest',
  	identityProvider: 'ICM',
[...]

import { overrides } from './environment.development';
import { ENVIRONMENT_DEFAULTS, Environment } from './environment.model';

export const environment: Environment = {
	...ENVIRONMENT_DEFAULTS,

  	icmChannel: 'inSPIRED-inTRONICS-Site',

  	features: ['compare', 'recently', 'rating', 'guestCheckout', 'wishlists'],

  	...overrides,
};

The switch to the headless application type requires adjustments regarding the changes in the used CMS content model. Almost all other parts work as before. This is also due to the fact that the application type is not used in any way to define whether the PWA acts as a B2C or B2B storefront. This is only controlled by the PWA deployment's enabled feature toggles.

However, there are changes required for handling the different /customers and /privatecustomers REST resources:  The /customers resource is used for user login. Once logged in, different resources must be used for further calls depending on whether the user is a business customer (/customers) or a private customer (/privatecustomers).

This distinction is currently made based on the presence of a customer.companyName (business customer) or its absence (private customer). This does not decide whether it is a B2B or a B2C shop. It could even be a mixed customers shop. It is only required to determine how REST calls for the currently logged-in user should be handled. It does not affect REST calls that are not based on the /customers resource.

There is also a handling implemented to ensure that the PWA is still compatible with the other application types intershop.B2CResponsive and intershop.SMBResponsive regarding the /customers resource.

We Use Custom Content. How Do We Migrate?

1. The ICM cartridges app_sf_base_cm and app_sf_pwa_cm have to be integrated into the project code.
2. The content that was used in the Responsive Starter Store must be exported, customized and imported into the new application. If necessary, project-specific customizations as well as includes can be transferred to the PWA application type.

What If We Want to Switch to the PWA Piece By Piece?

If you want to start using the PWA, it is possible to switch features from your responsive storefront piece by piece using a hybrid approach. This means, running Angular and the classic storefront in parallel, switching seamlessly between both. For example, a customer might start shopping in the Angular PWA, while the checkout process is handled by the classic storefront. Once the checkout process is complete, the Angular storefront takes over again.

The main purpose of this approach is to enable the use of all PWA features while adding Responsive Starter Store (RSS) features, since the PWA does not support all features available in the RSS. It is possible to move the available functionality to the Angular storefront by migration.

Please visit Hybrid Approach and Concept - Intershop Progressive Web App - Hybrid Approach for further details.