Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs][474350] Document the new starter template for SSR #694

Merged
merged 8 commits into from
May 27, 2021
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,14 @@ Note that these templates are examples of project starting points, and are not r

### Experimental Templates

Experimental templates are experimental specialized JSS examples. They are examples of how to do advanced tasks, but may not be stable or thoroughly documented.
Experimental templates are specialized JSS examples, showing how to do advanced tasks, but may not be stable, thoroughly documented, or supported.

* `react-native` The React Native Styleguide template
* `sitecore-embedded-jss-app` This app shows how to embed a JSS application inside an existing Sitecore site as a rendering. [Read more here](/docs/techniques/mvc-integration/client-side-embedding).

### Special Templates
* `node-headless-ssr-proxy` This app shows how to configure a Node server to act as a proxy between the browser and Sitecore. [Read more here](/docs/techniques/ssr/headless-mode-ssr).
* `node-headless-ssr-experience-edge` This app shows how to configure SSR for your JSS application using a Sitecore Experience Edge endpoint.

### Deprecated Templates
* `sitecore-javascript-renderings` This app shows how to render a JavaScript app as a rendering embedded within a traditional Sitecore MVC site. See [JavaScript Renderings](/docs/techniques/mvc-integration/javascript-rendering) for details. This template is flagged as deprecated as of Oct 2020 because these rendering don't scale well. They satisfy edge-case requirements, and should generally be avoided.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
name: ssr-experience-edge
routeTemplate: ./data/component-templates/article.yml
title: SSR using Sitecore Experience Edge
---

# Server-side rendering using Sitecore Experience Edge

You can configure server-side rendering (SSR) for your JSS application using a Sitecore Experience Edge endpoint.

Sitecore provides a [sample for server-side rendering using a Sitecore Experience Edge endpoint](https://github.com/Sitecore/jss/tree/dev/samples/node-headless-ssr-experience-edge), Node.js, and Express. It renders your JSS application, querying layout and dictionary data, without proxying the requests.

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

## Pre-requisites

To use this technique you need:

1. A Sitecore instance with [Headless Services installed](/docs/client-frameworks/getting-started/jss-server-install).

2. A Sitecore API key.

3. A React, Vue or Angular application built with JSS that:

- Supports [server-side rendering in integrated mode](/docs/techniques/ssr/integrated-mode-ssr).

- Supports the Experience Edge GraphQL schema.

> JSS applications, except those based on Next.js, still use the legacy/non-Edge GraphQL schema. You will need to update your application's GraphQL components and queries to be compatible with the Experience Edge schema. See the [GraphQL-ConnectedDemo](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/components/graphql/GraphQL-ConnectedDemo.tsx) component and [the associated GraphQL query](https://github.com/Sitecore/jss/blob/dev/samples/nextjs/src/components/graphql/GraphQL-ConnectedDemo.graphql) in the Next.js sample application.

- 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.

## How to use the sample

To use the SSR rendering with Sitecore Experience Edge:

1. Create the SSR application based on the `node-headless-ssr-experience-edge` sample. In this example, we name it `jss-edge`.

```
jss create jss-edge node-headless-ssr-experience-edge
```

2. In your React/Vue/Angular app's root directory, build your JSS app for production with `jss build`.

3. Copy the production build artifacts from your app (`/dist` or `/build` within the app) to the `sitecoreDistPath` set in your app's `package.json` under the SSR sample root path. For example `jss-edge/dist/<JSS app name>`.

> Alternatively, change the `instancePath` in your JSS app's `scjssconfig.json` to the SSR sample root path, and then use `jss deploy files` to complete the deployment to the SSR sample.

5. In `jss-edge/config.js`, set the values for:

- `appName` to the value set for your JSS application in `config.appName` in the `package.json` file.
- `bundlePath` to the path where you copied the built JSS app's `server.bundle.js`. For example: `'./dist/<JSS app name>/server.bundle'`.
- `endpoint` to your Experience Edge endpoint.
- `apiKey` to the API key provisioned on Sitecore Experience Edge.
- `defaultLanguage` to the JSS app's default language used to determine language context if the language is not specified in the request URL.
- `port` for starting the SSR sample.

Alternatively, you can define values for the [environment variables](#environment-variables) used by the SSR sample.

6. Test the SSR application by running `npm run start`.

## Environment Variables

The following environment variables can be set to configure the SSR sample instead of modifying `config.js`, for environments where this is more desirable like containers:

| Parameter | Description |
| ----------------------------------- | ------------------------------------------------------------ |
| `SITECORE_JSS_APP_NAME` | The JSS app's name. Used when request layout data and dictionary using graphql query and the default value of `SITECORE_JSS_SERVER_BUNDLE` if it's 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 JSS app's default language. Used to determine language context in case language is not specified in request URL. |
| `PORT` | Optional. Port which will be used when start sample. Default can be seen in [config.js](https://github.com/Sitecore/jss/blob/dev/samples/node-headless-ssr-experience-edge/config.js). |

4 changes: 4 additions & 0 deletions docs/src/app/components/Navigation/docs.js
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,10 @@ export default {
url: 'headless-mode-ssr',
displayName: 'via Headless Mode',
},
{
url: 'ssr-experience-edge',
displayName: 'using Experience Edge',
},
{
url: 'server-rendering-viewbag',
displayName: 'Adding Data for SSR',
Expand Down