Document Tree
    Document Properties
    Kbid
    3084Z0
    Last Modified
    28-Mar-2025
    Added to KB
    18-Apr-2023
    Public Access
    Everyone
    Status
    Online
    Doc Type
    Guidelines
    Product
    Intershop Progressive Web App
    Guide - Intershop Progressive Web App - Building and Running Server-Side Rendering

    Building

    To simply build the Intershop PWA in server-side rendering mode, you can use the package.json script npm run build, which builds the Intershop PWA with the production configuration of the angular.json with the default theme.
    Afterward, you can start the application with npm run serve (or do both by using npm run start).

    To build a specific theme (see Guide - Themes), you can build (and run) via npm using the --configuration= argument.
    All configuration options must be in the format --configuration=<theme>,(production|development).

    Building Multiple Themes

    The package.json property config.active-themes determines which themes should be built when running npm run build:multi.
    This will build server and client bundles for all active themes and supply them in the dist folder.
    The SSR process for each theme can be run individually using the generated scripts dist/<theme>/run-standalone.

    To run multiple themes with PM2, the script src/ssr/server-scripts/build-ecosystem.js can be used to generate the ecosystem.
    If only one theme is active, the theme-specific SSR process will be run in cluster mode on the default port.
    If more themes are active, PM2 is provisioned to run a distributor process in front of all theme-specific processes, to direct incoming traffic to the correct SSR process.

    The preferred way for production deployments is to build the Dockerfile in the project root and run the created image.
    This will automatically build all active themes and configure PM2 for running multiple themes in parallel.

    Running

    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, run, for example, set SSR_HYBRID=true on the command line before executing the npm run commands.

    If the format is any, the environment variable has to be set to any value to be active.
    Setting it to "false" still counts as active.
    Only empty strings count as inactive.

    If the format is switch, the property is switched on by supplying on, 1, yes or true (checked case-insensitive), anything else is considered off.

    All parameters are case-sensitive.
    Make sure to use them as written in the table below.

    parameter format comment
    SSR Specific PORT number Port for running the application
    CONCURRENCY_SSR number | max Concurrency for SSR instances per theme (default: 2)
    CACHE_ICM_CALLS recommended | JSON Enable caching for ICM calls, see Local ICM Cache (default: disabled)
    General ICM_BASE_URL string Sets the base URL for the ICM
    ICM_BASE_URL_SSR string Sets the base URL for the ICM used in SSR (optional)
    ICM_CHANNEL string Overrides the default channel
    ICM_APPLICATION string Overrides the default application
    FEATURES comma-separated list Overrides active features
    THEME string Overrides the default theme
    MULTI_SITE_LOCALE_MAP JSON | false Used to map locales to url modification parameters
    DEPLOY_URL string Set a Deploy URL (default /)
    Debug ⚠️ TRUST_ICM any Use this if ICM is deployed with an insecure certificate
    LOGGING switch Enables extra log output
    LOG_ALL switch Logs success and error messages (if false, only errors)
    SOURCE_MAPS switch Exposes source maps if activated
    Hybrid Approach SSR_HYBRID any Enables running PWA and ICM in the Hybrid Approach
    SSR_HYBRID_BACKEND URL When running in K8S, this contains the ICM WA service URL. For none K8S you can use ICM_BASE_URL
    PROXY_ICM any | URL Proxy ICM via /INTERSHOP (enabled if SSR_HYBRID is active)
    Third party GTM_TOKEN string Token for Google Tag Manager
    GMA_KEY string API key for Google Maps
    SENTRY_DSN string Sentry DSN URL for using Sentry Error Monitor
    PROMETHEUS switch Exposes Prometheus metrics
    METRICS_DETAIL_LEVEL string DEFAULT or DETAILED - see Guide - Monitoring with Prometheus
    IDENTITY_PROVIDER string ID of the default identity provider if other than ICM
    IDENTITY_PROVIDERS JSON Configuration of additional identity providers besides the default ICM
    ADDRESS_DOCTOR JSON Configuration of address doctor with login, password, maxResultCount and url
    COPILOT JSON Configuration of Intershop Copilot for Buyers

    Development

    For live Angular Universal (SSR) development, you have to use means provided by Angular CLI.
    The following command starts an SSR development environment.

    npm run start:ssr-dev
    

    If the SSR development environment needs to run with https, this can be achieved like this:

    npm run start:ssr-dev -- --ssl
    

    The following is an example command for how to provide specific certificates that can be valid in your local development environment:

    ng run intershop-pwa:serve-ssr --ssl --ssl-cert ~/work/wildcard-certificates/wildcard_localdev.de/cert.pem --ssl-key ~/work/wildcard-certificates/wildcard_localdev.de/privkey.pem --host host.localdev.de
    

    Local ICM Cache

    As there are multiple calls that are always common for any SSR requests (like retrieving /configurations, /localizations and category trees), those calls can be cached for a short time inside the PWA SSR process and be reused for multiple pre-renders.
    Set CACHE_ICM_CALLS=recommended to setup basic short-time caching for the aforementioned calls.

    You can further customize the caching by supplying a JSON structure to the CACHE_ICM_CALLS environment variable of the PWA SSR process:

    {
      "/configurations": "20m",
      "/variations": "2h",
      ".*": "2m"
    }

    This example will cache /configurations for 20 minutes, product variations for 2 hours, and everything else for 2 minutes.

    This feature can also be used to benchmark the SSR render performance locally by caching all ICM calls.

    Further References

    Disclaimer
    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.
    The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
    Home
    Knowledge Base
    Product Releases
    Log on to continue
    This Knowledge Base document is reserved for registered customers.
    Log on with your Intershop Entra ID to continue.
    Write an email to supportadmin@intershop.de if you experience login issues,
    or if you want to register as customer.