Walkthrough: Configuring the HTTP rendering engine for your JSS app

Current version: 20.x

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.

This walkthrough describes how to:

  • Configure the rendering engine server-side.

  • Configure the rendering engine client-side.

Configure the rendering engine server-side

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

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:

  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 client-side

To be able to render the JSS application server-side, you must configure the HTTP rendering engine on the client side too.


This procedure applies to React applications. For Vue.js and Angular applications, you must implement the rendering host build scripts.

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 example, for local testing, you can set it to http://localhost:5000:

      "config": {    
        "appName": "JssReactWeb",    
        "rootPlaceholders": [      
        "sitecoreDistPath": "/dist/JssReactWeb",    
        "sitecoreConfigPath": "/App_Config/Include/zzz",    
        "graphQLEndpointPath": "/sitecore/api/graph/edge",    
        "language": "en",    
        "tunnelUrl": "http://localhost:5000"  

    The build process uses the tunnelUrl value to convert all relative static asset URLs (images, JavaScript, and CSS files) to absolute URLs. As static assets are not displayed on Sitecore servers, this ensures that the remote Sitecore instance renders them correctly.

  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 process performs the same actions as the default build command but also replaces relative static asset URLs with absolute URLs based on the tunnelUrl setting.

  3. Register for an ngrok account and obtain an authentication token.


    Registering for an ngrok account is a required step because of changes in the service to prevent abuse. Without the authentication token, you cannot start the rendering host instance using the HTTP rendering engine and get the ngrok error 9018.

  4. In the scripts/http-renderer.js file, add the authentication token to the options of the startRenderHostTunnel function:

    startRenderHostTunnel('localhost', { port: 5000, authtoken: "<your-ngrok-authtoken>" })
  5. Run a rendering host instance on http://localhost:5000 (default) and start an 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 rendering your JSS app in the Experience Editor of a remote Sitecore instance for testing purposes.

Do you have some feedback for us?

If you have suggestions for improving this article,