Walkthrough: Configuring the HTTP rendering engine for your JSS app

Abstract

Set up the HTTP rendering engine for your JSS app

The HTTP rendering engine, or rendering host, requires client-side and server-side configuration of your JSS app. The following procedures apply to JSS applications based on the React, Angular, and Vue.js sample applications. JSS applications based on the Next.js sample are preconfigured to use the HTTP rendering engine.

For an example of setting up the rendering host, you can inspect the React sample app implementation.

This walkthrough describes how to:

  • Configure the rendering engine on the server-side.

  • Configure the rendering engine on the client-side.

Configure the rendering engine on the server-side

To set up the HTTP rendering engine on the server-side, you can opt for an absolute configuration or for setting the rendering host URL dynamically.

To configure a fixed rendering host URL, you must update your JSS app configuration.

To configure a fixed rendering host URL:

  1. In the Sitecore configuration file, for example, /sitecore/config/JssReactWeb.config, in the <app/> configuration, set the serverSideRenderingEngine attribute to http.

  2. Set the serverSideRenderingEngineEndpointUrl attribute to point to your rendering host URL. For example, http://localhost:5000.

Alternatively, to set the rendering host URL dynamically:

  1. In your HTTP rendering engine configuration file, for example \App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.ViewEngine.Http.config, set the value of the property AllowOptionsOverride to true:

    <AllowOptionsOverride>true</AllowOptionsOverride>
  2. Access a page using the sc_httprenderengineurl query string parameter. For example, http://mysitecore.local&sc_httprenderengineurl=https://2ea61a8f80b9.ngrok.io/api/editing/render.

Configure the rendering engine on the client-side

To run the rendering host:

  1. In the package.json file, in the config section, update the tunnelUrl setting to point to the URL of your rendering host. The rendering host can be a local or remote URL. For local testing, you can set it to http://localhost:5000. This URL is required at build time to replace all static asset URLs (such as images, JavaScript, and CSS files) to become absolute instead of relative. This ensures that static assets are rendered properly by a remote Sitecore instance because they are not deployed to Sitecore servers. For example:

      "config": {    
        "appName": "JssReactWeb",    
        "rootPlaceholders": [      
          "jss-main"    
        ],    
        "sitecoreDistPath": "/dist/JssReactWeb",    
        "sitecoreConfigPath": "/App_Config/Include/zzz",    
        "graphQLEndpointPath": "/sitecore/api/graph/edge",    
        "language": "en",    
        "tunnelUrl": "http://localhost:5000"  
      },
  2. Build the app for the rendering host and place it into the /build folder. In a terminal, run the following script:

    npm run build:rendering-host

    This build is not much different from the default build command. The key difference is that build:rendering-host replaces static asset URLs to be absolute, based on the tunnelUrl setting.

  3. Run a rendering host instance on http://localhost:5000 (default) and start a Ngrok tunnel. In a terminal, run the following script:

    npm run start:rendering-host

    The tunnel exposes your local rendering host to the outside world through a public HTTP endpoint. This can be useful when you want to render your JSS app in the Sitecore editor of a remote Sitecore instance for testing purposes.