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

Current version: 19.x

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:

A Sitecore instance with Headless Services installed.
A Sitecore API key.
A React, Vue.js, or Angular application built with JSS that:
- Supports server-side rendering in integrated mode.
- Supports the Experience Edge GraphQL schema.
  
  Important
  
  JSS applications, except those based on Next.js, still use the legacy/non-Edge GraphQL schema. You must update your GraphQL components and queries to be compatible with the Experience Edge schema.
- Provides the SITECORE_API_KEY. The GraphQLRequestClient uses the API key to set the sc_apikey header for authentication on both the Sitecore XM Edge schema and Sitecore Experience Edge.

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

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:
RequestResponseshell
```
   jss create jss-edge node-headless-ssr-experience-edge
```
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:
RequestResponseshell
```
jss build
```
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.
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.
In a terminal, at the root of the SSR jss-edge app, run the following script to test the SSR application:
RequestResponseshell
```
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 language context if language unspecified in the request URL.
`PORT`	Optional. Port used when starting the sample. See the default in config.js.