From cacf2b8d00a47123f2377057bd1e7cff693ce3b3 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 17 May 2021 16:57:11 +0200 Subject: [PATCH 1/8] Document node-headless-ssr-experience-edge --- .../ssr/sitecore-experience-edge/en.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md diff --git a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md new file mode 100644 index 0000000000..7bafd39fc2 --- /dev/null +++ b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md @@ -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. + + > 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/`. + +> 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 you JSS application in `package.json`. + - `bundlePath` to the path where you copied the built JSS app's `server.bundle.js`. For example: `'./dist//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). | + From 5fef6c2294bf1ca2ab02db134c848dbb0d9be86f Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 17 May 2021 16:57:30 +0200 Subject: [PATCH 2/8] Add nav item for SSR with Edge --- docs/src/app/components/Navigation/docs.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/src/app/components/Navigation/docs.js b/docs/src/app/components/Navigation/docs.js index c6a5b96a7c..6189f2ab81 100644 --- a/docs/src/app/components/Navigation/docs.js +++ b/docs/src/app/components/Navigation/docs.js @@ -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', From 32806821ca19a1ad397b67cdb77dc7af6973e835 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Tue, 25 May 2021 09:50:13 +0200 Subject: [PATCH 3/8] Emphasize the experimental nature of the template --- .../routes/docs/techniques/ssr/sitecore-experience-edge/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md index 7bafd39fc2..610a6c7ae6 100644 --- a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md +++ b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md @@ -10,7 +10,7 @@ You can configure server-side rendering (SSR) for your JSS application using a S 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. +> The sample for SSR using a Sitecore Experience Edge endpoint is _experimental_ and not officially supported by Sitecore. ## Pre-requisites From 7e7f29406c0e6801a53e52830f5c4c464a3c05aa Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Tue, 25 May 2021 09:51:09 +0200 Subject: [PATCH 4/8] Specify that non-next.js apps use legacy/non-Edge schema. --- .../routes/docs/techniques/ssr/sitecore-experience-edge/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md index 610a6c7ae6..2cabcd65f5 100644 --- a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md +++ b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md @@ -26,7 +26,7 @@ To use this technique you need: - Supports the Experience 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. + > 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. From e3a78c1eb305f8f93fc0f5da3ba00f01901fef80 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Tue, 25 May 2021 09:52:42 +0200 Subject: [PATCH 5/8] Fix typo, improve clarity --- .../routes/docs/techniques/ssr/sitecore-experience-edge/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md index 2cabcd65f5..a9325b2cb3 100644 --- a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md +++ b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md @@ -48,7 +48,7 @@ To use the SSR rendering with Sitecore Experience Edge: 5. In `jss-edge/config.js`, set the values for: - - `appName` to the value set for you JSS application in `package.json`. + - `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//server.bundle'`. - `endpoint` to your Experience Edge endpoint. - `apiKey` to the API key provisioned on Sitecore Experience Edge. From 6155736ad88bfc7bffd651ebaec67e95ff0e35c7 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Tue, 25 May 2021 09:53:14 +0200 Subject: [PATCH 6/8] Add ssr-edge sample to list of experimental templates --- .../docs/client-frameworks/getting-started/quick-start/en.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/data/routes/docs/client-frameworks/getting-started/quick-start/en.md b/docs/data/routes/docs/client-frameworks/getting-started/quick-start/en.md index a9f7ab55ad..579d3c9375 100644 --- a/docs/data/routes/docs/client-frameworks/getting-started/quick-start/en.md +++ b/docs/data/routes/docs/client-frameworks/getting-started/quick-start/en.md @@ -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. From 7fdf6fc10d422b7dbbbcb5a119433eb8e6caa5aa Mon Sep 17 00:00:00 2001 From: Anca Emcken <1617798+ancaemcken@users.noreply.github.com> Date: Wed, 26 May 2021 12:50:52 +0200 Subject: [PATCH 7/8] Review language --- .../ssr/sitecore-experience-edge/en.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md index a9325b2cb3..fcbb3d0435 100644 --- a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md +++ b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md @@ -8,13 +8,13 @@ title: SSR 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. +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: +To use this technique, you need: 1. A Sitecore instance with [Headless Services installed](/docs/client-frameworks/getting-started/jss-server-install). @@ -26,7 +26,7 @@ To use this technique you need: - 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. + > 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. @@ -42,7 +42,7 @@ To use the SSR rendering with Sitecore 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/`. +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/`. > 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. @@ -51,8 +51,8 @@ To use the SSR rendering with Sitecore Experience Edge: - `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//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. + - `apiKey` to the API key provisioned on Sitecore Experience Edge. + - `defaultLanguage` to the JSS app's default language used to determine language context if no language is 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. @@ -61,14 +61,14 @@ To use the SSR rendering with Sitecore Experience Edge: ## 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: +You can set the following environment variables 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_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 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). | +| `DEFAULT_LANGUAGE` | The JSS app's default language. 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](https://github.com/Sitecore/jss/blob/dev/samples/node-headless-ssr-experience-edge/config.js). | From a454cc00050d8f6a269877c1dd4d2919e33d44d3 Mon Sep 17 00:00:00 2001 From: Anca Emcken <1617798+ancaemcken@users.noreply.github.com> Date: Wed, 26 May 2021 14:41:26 +0200 Subject: [PATCH 8/8] Add third-party note on Node.js as per PBI 435247 --- .../docs/techniques/ssr/sitecore-experience-edge/en.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md index fcbb3d0435..c1db61e151 100644 --- a/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md +++ b/docs/data/routes/docs/techniques/ssr/sitecore-experience-edge/en.md @@ -8,7 +8,11 @@ title: SSR 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. +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. + + > NodeJS is a third-party technology that you must configure according to your specific use-case scenarios for Headless mode. + +The application 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.