docs: add headless app type migration information (#303)

* add PWA with headless application type migration information for the Hybrid Approach * add migration note for preventing switch to new application type Co-authored-by: Danilo Hoffmann <d.hoffmann@intershop.de> Co-authored-by: Marcus Schmidt <marcus.schmidt@intershop.de>
intershop · Jul 28, 2020 · 2c13f44 · 2c13f44
1 parent 04abd41
commit 2c13f44
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 3 deletions.
diff --git a/docs/concepts/hybrid-approach.md b/docs/concepts/hybrid-approach.md
@@ -50,6 +50,11 @@ intershop.WebServerSecureURL=https://<nginx>
 
 The server-side rendering process must be started with `SSR_HYBRID=1`.
 
+In addition, the PWA must be run with secure URLs as well.
+This can be achieved with `SSL=1`.
+
+**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
@@ -76,6 +81,27 @@ Each entry contains:
 The properties `icm` and `pwaBuild` can use [named capture groups](<https://2ality.com/2017/05/regexp-named-capture-groups.html#replace()-and-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](https://github.com/tc39/proposal-regexp-named-groups#implementations).
 
+## 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 and is not suitable for storefront setups using the hybrid approach.
+For this reason, the PWA must be adapted to work with the Responsive Starter Store again.
+
+**Migration Steps to prepare the PWA for the hybrid approach with the Responsive Starter Store**
+
+- Use a current PWA version
+- Revert the following Git commits:
+
+| commit                                                                                                  | comment                                                                                 |
+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [50dc72ef0](https://github.com/intershop/intershop-pwa/commit/50dc72ef083d6bee3c33edebef275b85762db618) | feat: switch to the new headless REST application type CMS content model (#302)         |
+| [741454c8c](https://github.com/intershop/intershop-pwa/commit/741454c8c839dd001a3943236172d75ffd05541d) | feat: switch to the new headless REST application type applications demo content (#302) |
+
+- Configure the correct `icmApplication` setting
+- Add needed PWA specific Content Includes in the Responsive Starter Store
+  - Via `componentEntryPointDefinitions` in the ICM project source code
+- Follow the Hybrid configuration setup
+
 # Further References
 
 - [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md)

diff --git a/docs/guides/migrations.md b/docs/guides/migrations.md
@@ -9,7 +9,10 @@ kb_sync_latest_only
 
 ## 0.22 to 0.23
 
-We removed deprecated exports concerning the NgRx testing refactorings introduced in version 0.21.
+We removed deprecated exports related to the NgRx testing refactorings introduced in version 0.21.
+
+We switched our main development to the new headless REST application type provided by ICM 7.10.21.0.
+If you are upgrading and want to continue using the Responsive Starter Store application types, do not cherry-pick the [commits that switch application types](https://github.com/intershop/intershop-pwa/compare/a63d2a2fc1ffdb404e6b1fe8ffb79310fa2ef60f...741454c8c839dd001a3943236172d75ffd05541d).
 
 ## 0.20 to 0.21
 

diff --git a/docs/guides/ssr-startup.md b/docs/guides/ssr-startup.md
@@ -18,8 +18,10 @@ By default the `production` configuration is built.
 
 ## Running
 
-Overwriting configurations of the PWA is entirely done by environment properties.
-We chose this approach to have the best compatibility with running the PWA from the command line or in an orchestrator.
+Overwriting configurations of the PWA is entirely done by environment variables.
+This approach was chosen to have the best possible compatibility when running the PWA either from the command line or in an orchestrator.
+
+To [set environment variables in windows](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) just run for example `set SSR_HYBRID=true` on the command line before executing the `npm run` commands.
 
 If the format is _any_, then the environment variable just has to be set to any value to be active.
 Setting it to `"false"` still counts as active.

diff --git a/src/hybrid/default-url-mapping-table.ts b/src/hybrid/default-url-mapping-table.ts
@@ -30,6 +30,11 @@ export const ICM_WEB_URL = '/INTERSHOP/web/WFS/$<channel>/$<lang>/$<application>
 
 /**
  * Mapping table for running PWA and ICM in parallel
+ *
+ * NOTE:
+ * THIS MAPPING TABLE IS JUST AN EXAMPLE IMPLEMENTATION.
+ * It does not define mappings for all routes that could be handled in the PWA or the ICM.
+ * It needs to be adapted according to the requirements of the particular project.
  */
 export const HYBRID_MAPPING_TABLE: HybridMappingEntry[] = [
   {