Skip to main content

Server-side render JSS apps headlessly using a Sitecore Experience Edge endpoint

Abstract

Quickly set up SSR with a Sitecore Experience Edge endpoint for your JSS React, Angular, or Vue.js apps powered by GraphQL.

If you want to server-side render (SSR) a React, Angular, or Vue.js application built with JSS using a Sitecore Experience Edge (GraphQL) endpoint, Sitecore provides a sample application to simplify the setup process.

The sample application node-headless-ssr-experience-edge for SSR using an Edge endpoint comes preconfigured with a Node.js and Express server and services for querying the endpoint.

Note

Node.js and Express are third-party technologies you must configure according to your specific use-case scenarios for Headless mode.

The application renders your JSS application, querying layout, and dictionary data using the JSS GraphQL services without proxying the requests.

Important

The sample for SSR using a Sitecore Experience Edge endpoint is experimental and not officially supported by Sitecore.

To use this technique, you must have:

To headlessly SSR a JSS React, Angular, or Vue.js app using the sample node-headless-ssr-experience-edge:

  1. In a terminal, run the following JSS command to create an application based on the node-headless-ssr-experience-edge sample, providing a name for the application, such as jss-edge:

       npx create-sitecore-jss node-headless-ssr-experience-edge --appName jss-edge
  2. In another terminal, in the root directory of the JSS app you want to SSR, build your JSS app for production by running the following script:

    jss build
  3. Copy the resulting directory, for example, dist or build, to the root directory of the SSR app jss-edge, for example, in a dist/<JSS app name>/ directory.

    Alternatively, in the JSS app, in the scjssconfig.json file, change the instancePath to the SSR sample root path. In the terminal, run the jss deploy files command to deploy the build result to the SSR app.

    Important

    The scjssconfig.json file might not exist if you have never connected your JSS app to Sitecore.

  4. In the SSR jss-edge app, inspect the config.js file and modify it (or use environment variables) to specify values for the following properties:

    • appName - the value for your JSS application, as set in the package.json file in the config.appName configuration.

    • bundlePath - the path where you copied the directory resulting from the build process server.bundle.js. For example: './dist/<JSS app name>/server.bundle'.

    • endpoint - your Sitecore Experience Edge endpoint.

    • apiKey - set to the API key provisioned on Sitecore Experience Edge.

    • defaultLanguage - set to the default language configured in your JSS app used to determine language context if no language is specified in the request URL.

    • port - for starting the SSR sample.

  5. In a terminal, at the root of the SSR jss-edge app, run the following script to test the SSR application:

    npm run start

Environment variables

You can set environment variables to configure the SSR application instead of modifying the config.js file for environments where this is more desirable, like containers.

You can set the environment variables in your hosting or container environment or the SSR application by using a library such as dotenv in the config.js file to read values from a .env file.

To configure the environment of the JSS app for SSR with a Sitecore Experience Edge endpoint, use the following variables:

Parameter

Description

SITECORE_JSS_APP_NAME

The JSS app's name. Used when requesting layout data and dictionary using GraphQL queries, and the default value of SITECORE_JSS_SERVER_BUNDLE is not set.

SITECORE_API_KEY

The API key provisioned on Sitecore Experience Edge.

SITECORE_JSS_SERVER_BUNDLE

Path to the JSS app's server.bundle.js file.

SITECORE_EXPERIENCE_EDGE_ENDPOINT

Sitecore Experience Edge endpoint.

DEFAULT_LANGUAGE

The default language configured in the JSS app you want to SSR. Used to determine the language context if the language is not specified in the request URL.

PORT

Optional. Port used when starting the sample.