The files in this gist demonstrate a fairly basic setup for a JSS rendering host.
DISCLAIMER: No guarantees that the code actually runs as-is. It was largely edited in place, so there may be typos or small syntax errors that you'll need to correct in your editor of choice. Feel free to leave a comment with any necessary fixes.
-
Sitecore config:
jss-app-config.config
This file is meant to show you how to setup your app config to use an external rendering host. -
Entry point:
jss-rendering-host-tunnel.js
This file creates a ngrok tunnel and then starts the rendering host server -
Rendering host server:
jss-rendering-host-server.js
This file starts an Express server that is responsible for handling rendering requests from Sitecore JSS as well as serving static assets for your JSS app. -
App rendering middleware:
jss-rendering-host-middleware.js
This file implements Express middleware that parses incoming (POST) rendering requests from Sitecore JSS, then renders a JSS app (typically viaserver.bundle.js
) to HTML and returns the HTML as response to the Sitecore JSS request.
If you want static assets (e.g. images, css) used by your app to resolve correctly when served by Sitecore, you must ensure that your app and assets are built for rendering remotely and that your rendering host can handle requests for static assets. Your app needs to be built or tokenized specifically for external rendering so that the HTML emitted by SSR uses absolute URLs for static assets (e.g. images, css). The absolute URLs should be the URL of your rendering host or the tunnel that is exposing your rendering host.
While this type of build/token replace process is currenty do-able if your rendering host hostname is known at build time, it becomes more challenging if it's a dynamically-created hostname (e.g. via ngrok) due to the way app bundles are usually built.
For testing/proof-of-concept purposes, if you are OK with your assets not resolving properly (e.g. images, css, js) and are more interested in just proving that the connection between Sitecore and Rendering Host works, then you can do the following:
npm run start:rendering-host
- this will start the rendering host with a ngrok tunnel URL
- copy the tunnel URL from the console output
- browse to your Sitecore site with the
?sc_httprenderengineurl=[my ngrok tunnel url]
querystring parameter- alternatively, if using SXA+JSS, you can edit the JSS site settings item, and set the
Server side rendering engine url
field to the ngrok tunnel URL. Then save.
- alternatively, if using SXA+JSS, you can edit the JSS site settings item, and set the
- REMINDER: when browsing in this mode, your app HTML will render, but it's likely that any static assets will 404 because they will be referenced in the HTML with relative URLs, e.g.
/static/css/main.css
, instead of absolute URLs, e.g.http://renderinghost/static/css/main.css
.
When the Sitecore JSS rendering engine makes a request to a rendering host, the rendering host URL can be resolved in several ways, here's a general outline of precedence:
-
QueryString:
sc_httprenderengineurl
parameter takes precedence over all other values when the<AllowOptionsOverride>true</AllowOptionsOverride>
setting istrue
for your JSS app. -
Session: when the
sc_httprenderengineurl
querystring parameter is provided, the value will be stored in server session so that you can navigate between routes without always needing to specify the qs param. If you want to clear the session value, end your Sitecore session as you see fit. Or, make a request with?sc_httprenderengineurl=
or?sc_httprenderengineurl=null
. -
JSS app config: if using SXA, this value is provided by the
Server side rendering engine url
field in the JSS+SXA site settings. If not using SXA, this value can be set in the<app />
config node via theserverSideRenderingEngineUrl
attribute. -
Rendering engine instance config: each JSS app can have it's own rendering engine configuration, example:
App_Config/Sitecore/JavaScriptServices/Sitecore.JavaScriptServices.ViewEngine.Http.Instance.config
. Check/sitecore/admin/showconfig.aspx
to determine resolved rendering engine config. -
Rendering engine default config:
App_Config/Sitecore/JavaScriptServices/Sitecore.JavaScriptServices.ViewEngine.Http.config