Related Github Documents
Document Properties
Last Modified
Added to KB
Public Access
Doc Type
Guidelines, Concepts & Cookbooks
Intershop Progressive Web App
Concept - Intershop Progressive Web App - Hybrid Approach

Hybrid Approach

This document describes how to run PWA and ICM in hybrid mode, so that pages from the Intershop Progressive Web App and pages from the classic storefront can be run in parallel.

A possible scenario would be to have the shopping experience with all its SEO optimizations handled by the PWA and to delegate highly customized parts of the checkout or my account area to the ICM.


The best way to deploy a Hybrid Approach installation is with the Intershop provided PWA Helm chart (0.4.0 and above).
How to configure the PWA Helm chart for the PWA and the ICM is explained in the according Hybrid mode paragraph.
The version requirements for the involved systems are the following.

  • Intershop 11
  • PWA 3.2.0

The functional requirements for the Hybrid Approach to work are already available with the following versions of ICM and PWA but this way they cannot be deployed together with a combined Helm chart.

  • ICM or
  • PWA 2.3.0

NOTE: The feature is based on the assumption that the PWA and the ICM can read and write each other's cookies. That means that cookies written by the PWA and ICM must have the same domain and the same path. This works since all Responsive Starter Store requests and responses are proxied through the PWA SSR simulating a common domain.

Architectural Concept

Hybrid Approach Architecture

For a minimal-invasive implementation, the mechanics for the hybrid approach are mainly implemented outside of the ICM and in deployment-specific components of the PWA.

The ICM is proxied in the express.js server of the server-side rendering process and hereby made available to the outside.
A newly introduced mapping table is also used to decide when an incoming request should be handled by the PWA or the ICM.
This mapping table is also used in the PWA for switching from the context of the single page application to the ICM.


Intershop Commerce Management

The ICM must be run with Secure URL-only Server Configuration, which can be done by adding SecureAccessOnly=true to the appserver configuration.

Furthermore the synchronization of the apiToken cookie must be switched on, so that users and baskets are synchronized between PWA and ICM.
See Concept - Integration of Progressive Web App and inSPIRED Storefront.

If you also want to support the correct handling for links generated in e-mails, the property intershop.WebServerSecureURL must point to nginx.

configuration via $SERVER/share/system/config/cluster/


configuration via icm_as Helm chart


Intershop Progressive Web App

The server-side rendering process must be started with SSR_HYBRID=1.

In addition, the PWA must be run with secure URLs as well.
See SSR Startup - Development for reference how you can achieve that locally.

⚠️ Only for development environments: It might be necessary to set TRUST_ICM=1 if the used development ICM is deployed with an insecure certificate.

Also, the Service Worker must be disabled for the PWA, as it installs itself into the browser of the client device and takes over the routing process, making it impossible to break out of the PWA and delegate to the ICM.

Mapping Table

The mapping table resides in the PWA source code and provides the page-specific mapping configuration for the hybrid approach.

    id: "Product Detail Page",
    icm: `${ICM_CONFIG_MATCH}/ViewProduct-Start.*(\\?|&)SKU=(?<sku>[\\w-]+).*$`,
    pwaBuild: `product/$<sku>${PWA_CONFIG_BUILD}`,
    pwa: `^.*/product/([\\w-]+).*$`,
    icmBuild: `ViewProduct-Start?SKU=$1`,
    handledBy: "icm"

Each entry contains:

  • A regular expression to detect a specific incoming URL as ICM or PWA URL (icm and pwa)
  • Corresponding instructions to build the matching URL of the counterpart (pwaBuild and icmBuild)
  • A property handledBy (either icm or pwa) to decide on the target upstream

The properties icm and pwaBuild can use named capture groups and are only used in the node.js process running on the server.
However, pwa and icmBuild are used in the client application where named capture groups are not yet supported by all browsers.

PWA Adaptions

With version 0.23.0 the PWA was changed to no longer reuse the Responsive Starter Store application types but rather be based upon the newly introduced headless application type for REST Clients - intershop.REST.
This application type is completely independent of the Responsive Starter Store.
For this reason, the PWA must be configured to know which application it has to use to work with the Responsive Starter Store again (hybridApplication).

Steps to prepare the PWA for the hybrid approach with the Responsive Starter Store

  • Use a current PWA version
  • Configure icmApplication setting to denote the intershop.REST based application used by the PWA (this is in the demo scenario just rest).
  • Configure hybridApplication setting to denote the Responsive Starter Store application (this is usually -).
  • Follow the Hybrid configuration setup

NOTE: If for some reason the CMS content of the Responsive Starter Store should directly be reused in the PWA in a hybrid approach, the PWA needs some code adaptions and has to use the same application as the Responsive Starter Store. For more details see the older version of this documentation - Hybrid Approach - PWA Adaptions (3.0.0).

Further References


The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources