From abbb6c7857969e8e629fede1c547ba262c6b0779 Mon Sep 17 00:00:00 2001 From: Adam Brauer Date: Mon, 8 Mar 2021 17:26:30 -0600 Subject: [PATCH 01/17] Progress on doc updates for SSG/SSR & REST/GraphQL app modes --- docs/assets/img/nextjs-sitecore-routing.svg | 2 +- .../nextjs/data-fetching/data-services/en.md | 2 +- .../walkthrough-jsscreate/en.md | 10 +++++-- .../docs/nextjs/page-routing/jss-routes/en.md | 2 +- .../page-routing/switching-to-ssr/en.md | 29 ++++++++++++++----- docs/src/app/components/Navigation/nextjs.js | 2 +- 6 files changed, 34 insertions(+), 13 deletions(-) diff --git a/docs/assets/img/nextjs-sitecore-routing.svg b/docs/assets/img/nextjs-sitecore-routing.svg index 6696f09168..c8373632e1 100644 --- a/docs/assets/img/nextjs-sitecore-routing.svg +++ b/docs/assets/img/nextjs-sitecore-routing.svg @@ -1,3 +1,3 @@ -

props

props
Bar Page
Bar Page
http://localhost:3000/foo/bar
http://localhost:3000/foo/bar
Next.js Route
Next.js Route
pages\[[...path]].tsx
pages\[[...path]].tsx
Page Props Factory
Page Props Factory
lib\page-props-factory.ts
lib\page-props-factory.ts
Layout Service
Layout Service
getStatic/ServerSideProps
getStatic/ServerSideProps

context

context
{
  params: {
    path: [ 'foo', 'bar' ]
  }
  ...
}
{...
{
  layoutData: {...},
  ...
}
{...
fetch layoutData
fetch layoutData
/sitecore/api/layout/render/jss?item=/foo/bar
/sitecore/api/layout/render/jss?item=/foo/barViewer does not support full SVG 1.1 \ No newline at end of file +

props

props
Bar Page
Bar Page
http://localhost:3000/foo/bar
http://localhost:3000/foo/bar
Next.js Route
Next.js Route
pages\[[...path]].tsx
pages\[[...path]].tsx
Page Props Factory
Page Props Factory
lib\page-props-factory.ts
lib\page-props-factory.ts
Layout Service
Layout Service
getStatic/ServerSideProps
getStatic/ServerSideProps

context

context
{
  params: {
    path: [ 'foo', 'bar' ]
  }
  ...
}
{...
{
  layoutData: {...},
  ...
}
{...
fetch layoutData
fetch layoutData
/sitecore/api/layout/render/jss?item=/foo/bar&...
/sitecore/api/layout/render/jss?item=/foo/bar...
GraphQL Edge
GraphQL Edge
query {
  layout(routePath:"/foo/bar", ...) {
    ...
  }
}
query {...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md index fd858d9e17..5576dc7205 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md @@ -54,7 +54,7 @@ The factory retrieves the `context` locale as configured in the `i18n` entry of ### layoutData -The `layoutData` prop stores `LayoutServiceData` from the Sitecore Layout Service provided by a `RestLayoutService` instance. The `RestLayoutServices` fetches `LayoutServiceData` using the Sitecore Layout Service REST API using Axios as the default data fetcher. In SSR mode, it will set up the required request and response `headers` using the attributes `context.req` and `context.res` to provide the ability to use [Sitecore Tracking](/docs/fundamentals/services/tracking#jss-tracking). +The `layoutData` prop stores `LayoutServiceData` from the Sitecore Layout Service provided by a `RestLayoutService` instance. The `RestLayoutServices` fetches `LayoutServiceData` using the Sitecore Layout Service REST API using Axios as the default data fetcher. In SSR mode, it will set up the required request and response `headers` using the attributes `context.req` and `context.res` to provide the ability to use [Sitecore Tracking & Analytics](/docs/nextjs/tracking-and-analytics/overview). ### dictionary diff --git a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md index e220d02d6f..95852a1ea0 100644 --- a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md +++ b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md @@ -13,7 +13,7 @@ We recommend this approach for Sitecore developers who use the [code-first devel ## TL;DR -To quickly scaffold a JSS Next.js application, run the following commands in a terminal: +To quickly scaffold a JSS Next.js application with default configuration, run the following commands in a terminal: ``` npm install -g @sitecore-jss/sitecore-jss-cli @@ -39,10 +39,15 @@ To create a JSS application, you must: 3. Run: ``` - jss create my-first-jss-app nextjs + jss create my-first-jss-app nextjs [--fetchMode {REST/GraphQL}] [--renderMode {SSG/SSR}] ``` The command will create the JSS Next.js application and install the required packages. + + You can use the optional parameters to customize the application: + + * `--fetchMode {REST/GraphQL}`: Specifies how Sitecore data (layout, dictionary) is fetched. Default is REST. + * `--renderMode {SSG/SSR}`: Specifies the Next.js pre-rendering mode of the main `[[...path]].tsx` route. Default is SSG. ## Run your application @@ -64,6 +69,7 @@ To connect your application to Sitecore, you must: 1. [Setup JSS Server Components](/docs/client-frameworks/getting-started/jss-server-install). 2. [Deploy the application to a Sitecore environment](/docs/client-frameworks/getting-started/app-deployment). +3. [Connect to the Experience Editor](/docs/nextjs/experience-editor/walkthrough). diff --git a/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md b/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md index c13c835e60..c5c1c17bee 100644 --- a/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md +++ b/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md @@ -18,7 +18,7 @@ Here's a high-level overview of the routing process. In the diagram above, you can see how the Next.js route is applied to Sitecore JSS. * The `[[...path]].tsx` Next.js route will catch any path and pass this information along to `getStaticProps` or `getServerSideProps` on the `context` object (as a tokenized array). -* The page props factory uses the path information to construct a normalized Sitecore item path. It then makes a request to the JSS [Layout Service](/docs/fundamentals/services/layout-service) to fetch layout data for the item. +* The *Page Props Factory* uses the path information to construct a normalized Sitecore item path. It then makes a request to the [Sitecore Layout Service REST API or Sitecore GraphQL "Edge" schema](/docs/nextjs/data-fetching/data-services) to fetch layout data for the item. ## i18n Routing diff --git a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md index 5543a081d5..737008633e 100644 --- a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md +++ b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md @@ -1,17 +1,32 @@ --- name: switching-to-ssr routeTemplate: ./data/component-templates/article.yml -title: Switching to SSR +title: Switching between SSG and SSR --- -# Walkthrough: Switching to Server-Side Rendering (SSR) +# Walkthrough: Switching between Static Site Generation (SSG) and Server-Side Rendering (SSR) -By default, the Next.js sample application uses a route optimized for Static Site Generation (SSG). However, we have also provided a working SSR route you can use: [`\pages_examples\[[..path]].SSR.tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages_examples/%5B%5B%2E%2E%2Epath%5D%5D.SSR.tsx). +The Next.js sample application `[[..path]].tsx` route can be optimized for either Static Site Generation (SSG) or Server-Side Rendering (SSR). -This file may be used as a starter for SSR routes in Next.js hybrid (both SSR & SSG) applications or may be used to switch the Next.js sample application to full SSR. +You can choose the initial render mode on `jss create` with the optional `--renderMode` parameter: + +``` +jss create my-first-jss-app nextjs [--renderMode {SSG/SSR}] +``` + +**SSG is used by default** if you omit the parameter. + +However, you may wish to switch the render mode after creation or reference both for Next.js hybrid (both SSR & SSG) applications. > See [Next.js documentation](https://nextjs.org/docs/basic-features/pages#two-forms-of-pre-rendering) to learn more about SSG, SSR, and hybrid modes of pre-rendering. -To switch the Next.js sample application to full SSR: +To switch the Next.js sample application from SSG to SSR: + +1. Move or delete `\pages\[[..path]].tsx` +2. Download [`[[..path]].SSR.tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.SSR.tsx) to `\pages\` and rename as `[[..path]].tsx` +3. Delete `\lib\sitemap-fetcher.ts` (optional) + +To switch the Next.js sample application from SSR to SSG: -1. Rename the `\pages\[[..path]].tsx` to `[[..path]].SSG.tsx` and move to `\pages_examples\` -2. Rename the `\pages_examples\[[..path]].SSR.tsx` to `\pages_examples\[[..path]].tsx` and move to `\pages\` \ No newline at end of file +1. Move or delete `\pages\[[..path]].tsx` +2. Download [`[[..path]].tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.tsx) to `\pages\` +3. Download [`sitemap-fetcher.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/sitemap-fetcher.ts) to `\lib\` \ No newline at end of file diff --git a/docs/src/app/components/Navigation/nextjs.js b/docs/src/app/components/Navigation/nextjs.js index 885928d905..82a713d645 100644 --- a/docs/src/app/components/Navigation/nextjs.js +++ b/docs/src/app/components/Navigation/nextjs.js @@ -82,7 +82,7 @@ export default { }, { url: 'switching-to-ssr', - displayName: 'Switching to SSR', + displayName: 'Switching between SSG and SSR', }, //{ // url: 'error-routes', From 2bffc2fe39ada6f79fbd57ee64c22d3a9b343a3f Mon Sep 17 00:00:00 2001 From: Adam Brauer Date: Tue, 9 Mar 2021 15:05:39 -0600 Subject: [PATCH 02/17] parameter rename --- .../getting-started-nextjs/walkthrough-jsscreate/en.md | 6 +++--- .../docs/nextjs/page-routing/switching-to-ssr/en.md | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md index 95852a1ea0..74d063f17a 100644 --- a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md +++ b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md @@ -39,15 +39,15 @@ To create a JSS application, you must: 3. Run: ``` - jss create my-first-jss-app nextjs [--fetchMode {REST/GraphQL}] [--renderMode {SSG/SSR}] + jss create my-first-jss-app nextjs [--fetchWith {REST/GraphQL}] [--prerender {SSG/SSR}] ``` The command will create the JSS Next.js application and install the required packages. You can use the optional parameters to customize the application: - * `--fetchMode {REST/GraphQL}`: Specifies how Sitecore data (layout, dictionary) is fetched. Default is REST. - * `--renderMode {SSG/SSR}`: Specifies the Next.js pre-rendering mode of the main `[[...path]].tsx` route. Default is SSG. + * `--fetchWith {REST|GraphQL}`: Specifies how Sitecore data (layout, dictionary) is fetched. Default is REST. + * `--prerender {SSG|SSR}`: Specifies the Next.js pre-rendering form for the primary `[[...path]].tsx` route. Default is SSG. ## Run your application diff --git a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md index 737008633e..371bc800c8 100644 --- a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md +++ b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md @@ -7,17 +7,17 @@ title: Switching between SSG and SSR The Next.js sample application `[[..path]].tsx` route can be optimized for either Static Site Generation (SSG) or Server-Side Rendering (SSR). -You can choose the initial render mode on `jss create` with the optional `--renderMode` parameter: +You can choose the initial pre-rendering form on `jss create` with the optional `--prerender` parameter: ``` -jss create my-first-jss-app nextjs [--renderMode {SSG/SSR}] +jss create my-first-jss-app nextjs [--prerender {SSG|SSR}] ``` **SSG is used by default** if you omit the parameter. -However, you may wish to switch the render mode after creation or reference both for Next.js hybrid (both SSR & SSG) applications. +However, you may wish to switch the pre-rendering form after creation or reference both for Next.js hybrid (both SSR & SSG) applications. -> See [Next.js documentation](https://nextjs.org/docs/basic-features/pages#two-forms-of-pre-rendering) to learn more about SSG, SSR, and hybrid modes of pre-rendering. +> See [Next.js documentation](https://nextjs.org/docs/basic-features/pages#two-forms-of-pre-rendering) to learn more about SSG, SSR, and hybrid forms of pre-rendering. To switch the Next.js sample application from SSG to SSR: From e8d450b5e6404082dcc0d5c0fb6d6a6aa37bfe37 Mon Sep 17 00:00:00 2001 From: Adam Brauer Date: Wed, 10 Mar 2021 12:34:08 -0600 Subject: [PATCH 03/17] Another batch of updates --- docs/assets/img/nextjs-sitecore-analytics.svg | 2 +- .../nextjs/data-fetching/data-services/en.md | 30 +++++++++++++------ .../nextjs/data-fetching/getStaticPaths/en.md | 4 +-- .../deploying-to-production/export/en.md | 1 + .../walkthrough-jsscreate/en.md | 2 +- .../docs/nextjs/page-routing/jss-routes/en.md | 2 +- .../page-routing/switching-to-ssr/en.md | 4 +-- .../configuration/en.md | 20 +++++++++++-- .../tracking-and-analytics/overview/en.md | 8 ++--- 9 files changed, 48 insertions(+), 25 deletions(-) diff --git a/docs/assets/img/nextjs-sitecore-analytics.svg b/docs/assets/img/nextjs-sitecore-analytics.svg index 4d626a903f..2dc6e76e9d 100644 --- a/docs/assets/img/nextjs-sitecore-analytics.svg +++ b/docs/assets/img/nextjs-sitecore-analytics.svg @@ -1,3 +1,3 @@ -
Page
Page
http://localhost:3000/page
http://localhost:3000/page
Next.js SSR Route
Next.js SSR Route
pages_examples\[[...path]].SSR.tsx
pages_examples\[[...path]].SSR.tsx
Page Props Factory
Page Props Factory
lib\page-props-factory.ts
lib\page-props-factory.ts
Layout Service
Layout Service
getServerSideProps
getServerSideProps
fetch layoutData
fetch layoutData
RestLayoutService
RestLayoutService
fetchLayoutData (with Header Passing)
fetchLayoutData (with Head...
Page
Page
Layout Service
Layout Service
Header Passing
Header Passing
Page Request / Response
Page Request / Response
Layout Service Request / Response
Layout Service Request / Response
Request
Request
Response
Respon...
Request
Request
Response
Respon...
  • cookie
  • user-agent
  • referer
  • X-Forwarded-For
cookieuser-agentrefere...
  • set-cookie
set-cookieViewer does not support full SVG 1.1 \ No newline at end of file +
Page
Page
http://localhost:3000/page
http://localhost:3000/page
Next.js SSR Route
Next.js SSR Route
pages\[[...path]].tsx
pages\[[...path]].tsx
Page Props Factory
Page Props Factory
lib\page-props-factory.ts
lib\page-props-factory.ts
Layout Service
Layout Service
getServerSideProps
getServerSideProps
fetch layoutData
fetch layoutData
RestLayoutService
RestLayoutService
fetchLayoutData (with Header Passing)
fetchLayoutData (with Head...
Page
Page
Layout Service
Layout Service
Header Passing
Header Passing
Page Request / Response
Page Request / Response
Layout Service Request / Response
Layout Service Request / Response
Request
Request
Response
Respon...
Request
Request
Response
Respon...
  • cookie
  • user-agent
  • referer
  • X-Forwarded-For
cookieuser-agentrefere...
  • set-cookie
set-cookieViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md index 5576dc7205..99f37932d0 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md @@ -13,14 +13,20 @@ JSS Next.js applications support both forms of pre-rendering provided by Next.js Next.js uses different data fetching strategies for each pre-rendering form. +> See the Next.js documentation on [Data Fetching](https://nextjs.org/docs/basic-features/data-fetching) for more information about Next.js data fetching functions, and the `context` argument. + ## JSS Next.js data fetching The JSS Next.js sample application includes usage examples for both data fetching strategies available in Next.js, as follows: -* `src/pages/[[path]].tsx` implements `GetStaticPaths` and `GetStaticProps` (SSG). -* `src/page_examples/[[path]].SSR.tsx` implements `GetServerSideProps` (SSR). +* [`src/pages/[[..path]].tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.tsx) implements `GetStaticPaths` and `GetStaticProps` (SSG). +* [`src/pages/[[..path]].SSR.tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.SSR.tsx) implements `GetServerSideProps` (SSR). -> See the Next.js documentation on [Data Fetching](https://nextjs.org/docs/basic-features/data-fetching) for more information about Next.js data fetching functions, and the `context` argument. +> You can choose the initial `[[..path]].tsx` pre-rendering form on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): +> +> ``` +> jss create my-first-jss-app nextjs [--prerender {SSG|SSR}] +> ``` In the preceding examples, the implementations of `GetStaticProps` and `GetServerSideProps` leverage the `SitecorePagePropsFactory`. See the `SitecorePagePropsFactory` definition in [`src/lib/page-props-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/page-props-factory.ts). @@ -42,11 +48,15 @@ export type SitecorePageProps = { ## Page `props` -To prepare the page `props`, the `SitecorePagePropsFactory` uses the [Layout Service](/docs/fundamentals/services/layout-service).and the [Dictionary Service](/docs/fundamentals/services/dictionary-service). +To prepare the page `props`, the `SitecorePagePropsFactory` uses the [Layout Service API](/docs/fundamentals/services/layout-service) and the [Dictionary Service API](/docs/fundamentals/services/dictionary-service). You may use either the REST-based or GraphQL-based dictionary and layout services depending on requirements. -> If you need additional data for every page, you should fetch it inside the `SitecorePagePropsFactory` and return it together with the other properties. +> You can choose the initial dictionary and layout data fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): +> +> ``` +> jss create my-first-jss-app nextjs [--fetchWith {REST|GraphQL}] +> ``` -> We are currently using standard REST-based dictionary and layout services. For Sitecore Experience Edge, we will soon provide GraphQL-based implementations. +> If you need additional data for every page, you should fetch it inside the `SitecorePagePropsFactory` and return it together with the other properties. ### locale @@ -54,11 +64,13 @@ The factory retrieves the `context` locale as configured in the `i18n` entry of ### layoutData -The `layoutData` prop stores `LayoutServiceData` from the Sitecore Layout Service provided by a `RestLayoutService` instance. The `RestLayoutServices` fetches `LayoutServiceData` using the Sitecore Layout Service REST API using Axios as the default data fetcher. In SSR mode, it will set up the required request and response `headers` using the attributes `context.req` and `context.res` to provide the ability to use [Sitecore Tracking & Analytics](/docs/nextjs/tracking-and-analytics/overview). +The `layoutData` prop stores `LayoutServiceData` from either the Sitecore Layout Service REST API (`RestLayoutService`) or the Sitecore GraphQL "Edge" schema (`GraphQLLayoutService`). See [Layout Service API reference](/docs/fundamentals/services/layout-service) for more information. + +In SSR context, it will send the `context.req` and `context.res` to provide the ability to use [Sitecore Tracking & Analytics](/docs/nextjs/tracking-and-analytics/overview). ### dictionary -The `dictionary` prop contains `DictionaryPhrases` from the Sitecore Dictionary Service. A `RestDictionaryService` instance fetches dictionary data for the given language using the Sitecore Dictionary Service REST API. The `RestDictionaryService` uses Axios as the default data fetcher. By default, `caching` is enabled, and the `cacheTimeout` is 60 sec. You can disable/enable caching using the `cacheEnabled` property, and you can customize cache timeout using the `cacheTimeout` property. +The `dictionary` prop contains `DictionaryPhrases` from either the Sitecore Dictionary Service REST API (`RestDictionaryService`) or the Sitecore GraphQL "Edge" schema (`GraphQLDictionaryService`). See [Dictionary Service API reference](/docs/fundamentals/services/dictionary-service) for more information. ### componentProps @@ -72,4 +84,4 @@ If the Layout Service returns a `404` status for our page route, it will update ## Experience Editor (Next.js Preview Context) -While working in the Experience Editor, the sample Next.js application is in [preview](https://nextjs.org/docs/advanced-features/preview-mode) mode. The `SitecorePagePropsFactory` uses the `editingDataService`. The service uses `layoutData`, `dictionary`, and `language` data sent with the editing request in `context.previewData`. +While working in the Experience Editor, the sample Next.js application is in [preview mode](https://nextjs.org/docs/advanced-features/preview-mode). In this case the `SitecorePagePropsFactory` uses the `editingDataService` to retrieve `layoutData`, `dictionary`, and `language` data sent with the editing request. See [Experience Editor Integration Architecture](/docs/nextjs/experience-editor/architecture) for more information. \ No newline at end of file diff --git a/docs/data/routes/docs/nextjs/data-fetching/getStaticPaths/en.md b/docs/data/routes/docs/nextjs/data-fetching/getStaticPaths/en.md index 5667fb775f..667cc578c8 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/getStaticPaths/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/getStaticPaths/en.md @@ -5,9 +5,7 @@ title: getStaticPaths and the Sitemap Service --- # getStaticPaths and the Sitemap Service - - -Next.js provides the ability to generate pages with dynamic routes. +Next.js provides the ability to generate static pages with dynamic routes. If a page has [dynamic routes](https://nextjs.org/docs/routing/dynamic-routes) and uses [getStaticProps](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation), you can define a list of paths that you want pre-render to HTML at build time. diff --git a/docs/data/routes/docs/nextjs/deploying-to-production/export/en.md b/docs/data/routes/docs/nextjs/deploying-to-production/export/en.md index 63079f30c8..39c87cc21a 100644 --- a/docs/data/routes/docs/nextjs/deploying-to-production/export/en.md +++ b/docs/data/routes/docs/nextjs/deploying-to-production/export/en.md @@ -9,6 +9,7 @@ You can serve your JSS Next.js application as static HTML files using any static > Static HTML export does not support: > +> * Server-side Rendered (SSR) pages (using `getServerSideProps`). > * Internationalized routing. > * Request rewrites. > * Visitor identification. diff --git a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md index 74d063f17a..45b935d27e 100644 --- a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md +++ b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md @@ -39,7 +39,7 @@ To create a JSS application, you must: 3. Run: ``` - jss create my-first-jss-app nextjs [--fetchWith {REST/GraphQL}] [--prerender {SSG/SSR}] + jss create my-first-jss-app nextjs [--fetchWith {REST|GraphQL}] [--prerender {SSG|SSR}] ``` The command will create the JSS Next.js application and install the required packages. diff --git a/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md b/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md index c5c1c17bee..f09f8181de 100644 --- a/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md +++ b/docs/data/routes/docs/nextjs/page-routing/jss-routes/en.md @@ -18,7 +18,7 @@ Here's a high-level overview of the routing process. In the diagram above, you can see how the Next.js route is applied to Sitecore JSS. * The `[[...path]].tsx` Next.js route will catch any path and pass this information along to `getStaticProps` or `getServerSideProps` on the `context` object (as a tokenized array). -* The *Page Props Factory* uses the path information to construct a normalized Sitecore item path. It then makes a request to the [Sitecore Layout Service REST API or Sitecore GraphQL "Edge" schema](/docs/nextjs/data-fetching/data-services) to fetch layout data for the item. +* The *Page Props Factory* uses the path information to construct a normalized Sitecore item path. It then makes a request to the [Sitecore Layout Service REST API or Sitecore GraphQL "Edge" schema](/docs/nextjs/data-fetching/data-services#page-props) to fetch layout data for the item. ## i18n Routing diff --git a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md index 371bc800c8..db964a4652 100644 --- a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md +++ b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md @@ -7,14 +7,12 @@ title: Switching between SSG and SSR The Next.js sample application `[[..path]].tsx` route can be optimized for either Static Site Generation (SSG) or Server-Side Rendering (SSR). -You can choose the initial pre-rendering form on `jss create` with the optional `--prerender` parameter: +You can choose the initial pre-rendering form on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): ``` jss create my-first-jss-app nextjs [--prerender {SSG|SSR}] ``` -**SSG is used by default** if you omit the parameter. - However, you may wish to switch the pre-rendering form after creation or reference both for Next.js hybrid (both SSR & SSG) applications. > See [Next.js documentation](https://nextjs.org/docs/basic-features/pages#two-forms-of-pre-rendering) to learn more about SSG, SSR, and hybrid forms of pre-rendering. diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md index e3b2241bfc..4e8695ada8 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md @@ -9,17 +9,31 @@ This topic will guide you through the steps required to enable full Sitecore tra > See [Sitecore Experience Platform documentation](https://doc.sitecore.com/developers/101/sitecore-experience-platform/en/web-tracking.html) for more information about tracking and analytics. -Note this is different than *client-side tracking* via the JSS tracking API, which is possible for *both Static Site Generation (SSG) and Server-side Rendering (SSR)*. Please see the [JSS Tracking](/docs/fundamentals/services/tracking) page for details. +> Note this is different than *client-side tracking* via the JSS tracking API, which is possible for *both Static Site Generation (SSG) and Server-side Rendering (SSR)*. Please see the [JSS Tracking](/docs/fundamentals/services/tracking) page for details. ## Next.js application ### SSR only -You must use a Next.js SSR page route. An example SSR route is included with the Next.js sample app. See [this page](/docs/nextjs/page-routing/switching-to-ssr) for details. +You must use a Next.js SSR page route. You can choose the initial pre-rendering form of `[[..path]].tsx` on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): + +``` +jss create my-first-jss-app nextjs --prerender SSR +``` + +You can also switch the `[[..path]].tsx` route from SSG to SSR. See [this page](/docs/nextjs/page-routing/switching-to-ssr) for details. ### Layout Service requests -[Sitecore Layout Service](/docs/fundamentals/services/layout-service) requests must: +You must use the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). You can choose the initial fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): + +``` +jss create my-first-jss-app nextjs --fetchWith REST +``` + +> Tracking and Analytics is currently not supported with the Sitecore GraphQL "Edge" schema. + +Sitecore Layout Service requests must: 1. have tracking enabled (see [`tracking` parameter](/docs/fundamentals/services/layout-service#using-the-layout-service)), and 2. perform [header passing](/docs/nextjs/tracking-and-analytics/overview#header-passing) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md index f06a373024..c68c2472ec 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md @@ -5,11 +5,11 @@ title: Overview and architecture --- # Tracking & Analytics Overview and Architecture -Full Sitecore analytics and personalization functionality is possible with Next.js on any SSR (Server-side Rendered) page route. +Full Sitecore analytics and personalization functionality is possible with Next.js on any SSR (Server-side Rendered) page route using the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). -> Note [client-side JSS tracking](/docs/fundamentals/services/tracking) is possible for *both SSG and SSR*. +> See [Sitecore Experience Platform documentation](https://doc.sitecore.com/developers/101/sitecore-experience-platform/en/web-tracking.html) for more information about tracking and analytics. -> By default, the Next.js sample application uses a route optimized for SSG, but can be switched to SSR. See [here](/docs/nextjs/page-routing/switching-to-ssr) for steps. +> Note this is different than *client-side tracking* via the JSS tracking API, which is possible for *both Static Site Generation (SSG) and Server-side Rendering (SSR)*. Please see the [JSS Tracking](/docs/fundamentals/services/tracking) page for details. For Sitecore analytics and personalization to work with JSS, the appropriate HTTP headers must be present at the browser and Layout Service. @@ -19,7 +19,7 @@ With Next.js, this is accomplished by passing specific HTTP headers between the ## Header Passing -Here's how header passing works during a page request/response cycle. The flow is based on using the SSR page route example `pages_examples\[[...path]].SSR.tsx` that comes with the Next.js sample application. +Here's how header passing works during a page request/response cycle. The flow is based on using the [SSR `[[..path]].tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.SSR.tsx) route example that comes with the Next.js sample application. Next.js Sitecore Analytics From 83c6e31dc62e474b96dc31906d408d7395cbc5ce Mon Sep 17 00:00:00 2001 From: Adam Brauer Date: Wed, 10 Mar 2021 13:19:20 -0600 Subject: [PATCH 04/17] Added 'Switching between REST and GraphQL' doc, minor cleanup --- .../nextjs/data-fetching/data-services/en.md | 6 ++-- .../switching-fetch-method/en.md | 28 +++++++++++++++++++ .../page-routing/switching-to-ssr/en.md | 2 +- .../configuration/en.md | 2 +- docs/src/app/components/Navigation/nextjs.js | 4 +++ 5 files changed, 38 insertions(+), 4 deletions(-) create mode 100644 docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md diff --git a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md index 99f37932d0..aa7c280fda 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md @@ -25,7 +25,7 @@ The JSS Next.js sample application includes usage examples for both data fetchin > You can choose the initial `[[..path]].tsx` pre-rendering form on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): > > ``` -> jss create my-first-jss-app nextjs [--prerender {SSG|SSR}] +> jss create my-first-jss-app nextjs --prerender {SSG|SSR} > ``` In the preceding examples, the implementations of `GetStaticProps` and `GetServerSideProps` leverage the `SitecorePagePropsFactory`. See the `SitecorePagePropsFactory` definition in [`src/lib/page-props-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/page-props-factory.ts). @@ -53,8 +53,10 @@ To prepare the page `props`, the `SitecorePagePropsFactory` uses the [Layout Ser > You can choose the initial dictionary and layout data fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): > > ``` -> jss create my-first-jss-app nextjs [--fetchWith {REST|GraphQL}] +> jss create my-first-jss-app nextjs --fetchWith {REST|GraphQL} > ``` +> +> You can also [switch the fetch method](/docs/nextjs/data-fetching/switching-fetch-method). > If you need additional data for every page, you should fetch it inside the `SitecorePagePropsFactory` and return it together with the other properties. diff --git a/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md b/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md new file mode 100644 index 0000000000..7bc4f5d0bb --- /dev/null +++ b/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md @@ -0,0 +1,28 @@ +--- +name: switching-fetch-method +routeTemplate: ./data/component-templates/article.yml +title: Switching between REST and GraphQL +--- +# Walkthrough: Switching between REST and GraphQL for Layout and Dictionary data + +The Next.js sample application can use either the Sitecore Layout Service REST API or the Sitecore GraphQL "Edge" schema to fetch layout and dictionary data. + +> See [Layout Service API reference](/docs/fundamentals/services/layout-service) and [Dictionary Service API reference](/docs/fundamentals/services/dictionary-service) for more information. + +You can choose the initial dictionary and layout data fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): + +``` +jss create my-first-jss-app nextjs --fetchWith {REST|GraphQL} +``` + +However, you may wish to switch the fetch method after creation. + +To switch the Next.js sample application from REST to GraphQL: + +1. Move or delete `\lib\dictionary-service-factory.ts` +2. Download [`dictionary-service-factory.graphql.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/dictionary-service-factory.graphql.ts) to `\lib\` and rename as `dictionary-service-factory.ts` + +To switch the Next.js sample application from GraphQL to REST: + +1. Move or delete `\lib\dictionary-service-factory.ts` +2. Download [`dictionary-service-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/dictionary-service-factory.ts) to `\lib\` \ No newline at end of file diff --git a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md index db964a4652..8a3339545a 100644 --- a/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md +++ b/docs/data/routes/docs/nextjs/page-routing/switching-to-ssr/en.md @@ -10,7 +10,7 @@ The Next.js sample application `[[..path]].tsx` route can be optimized for eithe You can choose the initial pre-rendering form on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): ``` -jss create my-first-jss-app nextjs [--prerender {SSG|SSR}] +jss create my-first-jss-app nextjs --prerender {SSG|SSR} ``` However, you may wish to switch the pre-rendering form after creation or reference both for Next.js hybrid (both SSR & SSG) applications. diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md index 4e8695ada8..c12f78065c 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md @@ -21,7 +21,7 @@ You must use a Next.js SSR page route. You can choose the initial pre-rendering jss create my-first-jss-app nextjs --prerender SSR ``` -You can also switch the `[[..path]].tsx` route from SSG to SSR. See [this page](/docs/nextjs/page-routing/switching-to-ssr) for details. +You can also [switch the `[[..path]].tsx` route from SSG to SSR](/docs/nextjs/page-routing/switching-to-ssr). ### Layout Service requests diff --git a/docs/src/app/components/Navigation/nextjs.js b/docs/src/app/components/Navigation/nextjs.js index 82a713d645..5fd37ec5b1 100644 --- a/docs/src/app/components/Navigation/nextjs.js +++ b/docs/src/app/components/Navigation/nextjs.js @@ -110,6 +110,10 @@ export default { url: 'component-level-data-fetching', displayName: 'Component-level data fetching', }, + { + url: 'switching-fetch-method', + displayName: 'Switching between REST and GraphQL', + } ], }, { From bbdcd0e4ea28cd696f7f6d5004652555656d5aff Mon Sep 17 00:00:00 2001 From: Anastasiya Flynn Date: Wed, 17 Mar 2021 11:45:56 -0400 Subject: [PATCH 05/17] Update "Tracking & Analytics Overview and Architecture" docs Explicitly state that SSR is required for personalization, to avoid confusion --- .../routes/docs/nextjs/tracking-and-analytics/overview/en.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md index c68c2472ec..2f56970fc0 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md @@ -5,7 +5,7 @@ title: Overview and architecture --- # Tracking & Analytics Overview and Architecture -Full Sitecore analytics and personalization functionality is possible with Next.js on any SSR (Server-side Rendered) page route using the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). +Sitecore analytics and personalization functionality is possible with Next.js only on SSR (Server-side Rendered) page routes using the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). > See [Sitecore Experience Platform documentation](https://doc.sitecore.com/developers/101/sitecore-experience-platform/en/web-tracking.html) for more information about tracking and analytics. @@ -39,4 +39,4 @@ The `RestLayoutService` (part of the `@sitecore-jss/sitecore-jss-nextjs` npm pac ## Configuration -The Next.js sample application includes all configuration necessary to start using Sitecore analytics and personalization with Next.js SSR. However, additional steps may be required. Refer to [Enabling tracking and analytics](/docs/nextjs/tracking-and-analytics/configuration) for details. \ No newline at end of file +The Next.js sample application includes all configuration necessary to start using Sitecore analytics and personalization with Next.js SSR. However, additional steps may be required. Refer to [Enabling tracking and analytics](/docs/nextjs/tracking-and-analytics/configuration) for details. From aaf18e75f4a2e7d2347fe18c018ea11f252b960a Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Fri, 19 Mar 2021 09:15:29 +0100 Subject: [PATCH 06/17] Add jss create to CLI reference docs --- docs/data/routes/docs/fundamentals/cli/en.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/data/routes/docs/fundamentals/cli/en.md b/docs/data/routes/docs/fundamentals/cli/en.md index a2b779dadd..1cbf6fcb74 100644 --- a/docs/data/routes/docs/fundamentals/cli/en.md +++ b/docs/data/routes/docs/fundamentals/cli/en.md @@ -12,6 +12,26 @@ During JSS development, you will be commonly using scripts provided by the _JSS These are the main scripts you will be using frequently during JSS development. These were partially covered in [Quick start](/docs/client-frameworks/getting-started/quick-start). +### `jss create` +Creates a JSS application. You must provide an application name and a framework. + +``` +jss create +``` + +|Parameter| Options | Description| Default |Template| +|--- | --- | --- | --- | --- | +|`fetchWith` | `REST` or `GraphQL` | Specifies how the applicaiton should fetch Sitecore data (layout, dictionary). | `REST` | nextjs | +|`prerender` | `SSG` or `SSR` | Specifies the Next.js pre-rendering form for the primary `[[...path]].tsx` route. | `SSG` | nextjs | +|`repository` | A repository: githubusername/reponame | Specifies which repository to use for creating the JSS app | `Sitecore/jss` | all | +|`branch` | A branch name | Specifies which branch to use for creating the JSS app | `master` | all | +|`source` | A local directory path | Specifies a local directory for custom JSS app templates | - | all | + +**Example** +``` +jss create my-jss-app nextjs --prerender SSG --fetchWith GraphQL +``` + ### `jss setup` Runs the interactive setup process where you will optionally provide info about connecting/deploying to a Sitecore instance. The input is saved to `scjssconfig.json` file in the app root. From 2ff58eb4ef071bfa44f7f68a6b4ace14dd5ab5ed Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Fri, 19 Mar 2021 09:16:32 +0100 Subject: [PATCH 07/17] Add reference to CLI doc --- .../nextjs/data-fetching/data-services/en.md | 20 ++++++------------- .../walkthrough-jsscreate/en.md | 8 +------- 2 files changed, 7 insertions(+), 21 deletions(-) diff --git a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md index aa7c280fda..a7205be202 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md @@ -6,7 +6,7 @@ title: Data services used by Next.js with JSS # Data Services Used by Next.js with JSS -JSS Next.js applications support both forms of pre-rendering provided by Next.js: +A Next.js-based JSS applications support both forms of pre-rendering provided by Next.js: * Static Site Generation (SSG) * Server-side Rendering (SSR). @@ -22,13 +22,9 @@ The JSS Next.js sample application includes usage examples for both data fetchin * [`src/pages/[[..path]].tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.tsx) implements `GetStaticPaths` and `GetStaticProps` (SSG). * [`src/pages/[[..path]].SSR.tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.SSR.tsx) implements `GetServerSideProps` (SSR). -> You can choose the initial `[[..path]].tsx` pre-rendering form on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): -> -> ``` -> jss create my-first-jss-app nextjs --prerender {SSG|SSR} -> ``` +> You can choose the initial pre-rendering form for `[[..path]].tsx` during the application creation step with the optional `prerender` parameter. Consult the [JSS CLI reference](/docs/fundamentals/cli) for details about `jss create`. -In the preceding examples, the implementations of `GetStaticProps` and `GetServerSideProps` leverage the `SitecorePagePropsFactory`. See the `SitecorePagePropsFactory` definition in [`src/lib/page-props-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/page-props-factory.ts). +In the preceding examples, the implementations of `GetStaticProps` and `GetServerSideProps` leverage the `SitecorePagePropsFactory`. See the `SitecorePagePropsFactory` definition in [`src/lib/page-props-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/page-props-factory.ts). The factory exposes the method `create(context: GetServerSidePropsContext | GetStaticPropsContext)` that is responsible for fetching all data needed to render the page (the page `props`), depending on the `context` in which it is used. @@ -50,13 +46,9 @@ export type SitecorePageProps = { To prepare the page `props`, the `SitecorePagePropsFactory` uses the [Layout Service API](/docs/fundamentals/services/layout-service) and the [Dictionary Service API](/docs/fundamentals/services/dictionary-service). You may use either the REST-based or GraphQL-based dictionary and layout services depending on requirements. -> You can choose the initial dictionary and layout data fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): -> -> ``` -> jss create my-first-jss-app nextjs --fetchWith {REST|GraphQL} -> ``` -> -> You can also [switch the fetch method](/docs/nextjs/data-fetching/switching-fetch-method). +> You can choose the initial dictionary and layout data fetch method during the application creation step with the optional `fetchWith` parameter. Consult the [JSS CLI reference](/docs/fundamentals/cli) for details about `jss create`. + +> You can [switch the fetch method](/docs/nextjs/data-fetching/switching-fetch-method) after project creation. > If you need additional data for every page, you should fetch it inside the `SitecorePagePropsFactory` and return it together with the other properties. diff --git a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md index 45b935d27e..fcb0947d23 100644 --- a/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md +++ b/docs/data/routes/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate/en.md @@ -44,10 +44,7 @@ To create a JSS application, you must: The command will create the JSS Next.js application and install the required packages. - You can use the optional parameters to customize the application: - - * `--fetchWith {REST|GraphQL}`: Specifies how Sitecore data (layout, dictionary) is fetched. Default is REST. - * `--prerender {SSG|SSR}`: Specifies the Next.js pre-rendering form for the primary `[[...path]].tsx` route. Default is SSG. + > For more information on `jss create` see [the JSS CLI reference](/docs/fundamentals/cli). ## Run your application @@ -70,6 +67,3 @@ To connect your application to Sitecore, you must: 1. [Setup JSS Server Components](/docs/client-frameworks/getting-started/jss-server-install). 2. [Deploy the application to a Sitecore environment](/docs/client-frameworks/getting-started/app-deployment). 3. [Connect to the Experience Editor](/docs/nextjs/experience-editor/walkthrough). - - - From 8eb45192d963de2a4235106bca94a248dd8a254b Mon Sep 17 00:00:00 2001 From: Adam Brauer Date: Fri, 19 Mar 2021 07:49:47 -0500 Subject: [PATCH 08/17] Added clarification to analytics support (SSR with Sitecore Layout Service REST API only) to "How is Next.js Different" doc --- .../nextjs/getting-started-nextjs/how-is-nextjs-different/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/nextjs/getting-started-nextjs/how-is-nextjs-different/en.md b/docs/data/routes/docs/nextjs/getting-started-nextjs/how-is-nextjs-different/en.md index 46d57fe6f0..b989d0d78c 100644 --- a/docs/data/routes/docs/nextjs/getting-started-nextjs/how-is-nextjs-different/en.md +++ b/docs/data/routes/docs/nextjs/getting-started-nextjs/how-is-nextjs-different/en.md @@ -12,7 +12,7 @@ The Next.js SDK for Sitecore has some key differences from other Sitecore JavaSc * The _Headless SSR Proxy_ is not required for [production deployment](/docs/nextjs/deploying-to-production/deployment-options). * Next.js has built-in pre-rendering. * Next.js has [built-in rewrite / proxying support](https://nextjs.org/docs/api-reference/next.config.js/rewrites#rewriting-to-an-external-url) - * Sitecore tracking and analytics are supported through [header passing](/docs/nextjs/tracking-and-analytics/overview) (SSR-only). + * Sitecore tracking and analytics are supported through [header passing](/docs/nextjs/tracking-and-analytics/overview) (SSR with Sitecore Layout Service REST API only). * [Experience Editor integration](/docs/nextjs/experience-editor/walkthrough) does not require a separate deployment, and only supports the [HTTP Rendering Engine](/docs/fundamentals/services/view-engine#http-rendering-engine). * There is no requirement to install node.js on your Sitecore Content Management role. * There is never a need to deploy your application to the Sitecore Content Management role. From 59dcae42819b90de11d099730ef507ed750bdb58 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 22 Mar 2021 10:46:56 +0100 Subject: [PATCH 09/17] Provide more detailed example for `jss create` with optional params --- docs/data/routes/docs/fundamentals/cli/en.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/data/routes/docs/fundamentals/cli/en.md b/docs/data/routes/docs/fundamentals/cli/en.md index 1cbf6fcb74..cf5e347dfa 100644 --- a/docs/data/routes/docs/fundamentals/cli/en.md +++ b/docs/data/routes/docs/fundamentals/cli/en.md @@ -27,9 +27,13 @@ jss create |`branch` | A branch name | Specifies which branch to use for creating the JSS app | `master` | all | |`source` | A local directory path | Specifies a local directory for custom JSS app templates | - | all | -**Example** +**Examples** ``` +// Next.js-based application with Static Generation and fetching data using GraphQL jss create my-jss-app nextjs --prerender SSG --fetchWith GraphQL + +// Next.js-based application with Server-Side Rendering and fetching data using REST +jss create my-jss-app nextjs --prerender SSR --fetchWith REST ``` ### `jss setup` From 91d50e8f89f4190a7c59c7e5cb0ed2a4cdcab058 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 22 Mar 2021 10:47:50 +0100 Subject: [PATCH 10/17] Concentrate REST & SSR info in a pre-requisites section & clean up --- .../configuration/en.md | 30 ++++++++----------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md index c12f78065c..790d9a4844 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md @@ -13,36 +13,32 @@ This topic will guide you through the steps required to enable full Sitecore tra ## Next.js application -### SSR only +### SSR & REST only -You must use a Next.js SSR page route. You can choose the initial pre-rendering form of `[[..path]].tsx` on create with the optional `prerender` parameter. SSG is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): +JSS supports tracking and analytics only for server-side rendered applications using the REST fetch method. You can not currently use Tracking and Analytics with the Sitecore GraphQL "Edge" schema. -``` -jss create my-first-jss-app nextjs --prerender SSR -``` +**Pre-requisites** +- The application uses the SSR pre-rendering form. +- The application uses the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). -You can also [switch the `[[..path]].tsx` route from SSG to SSR](/docs/nextjs/page-routing/switching-to-ssr). +> You can choose the pre-rendering form and the fetch method when creating the project with the JSS CLI. For details, consult the [JSS CLI reference](/docs/fundamentals/cli). -### Layout Service requests +> If your application currently uses SSG, you can [switch the `[[..path]].tsx` route from SSG to SSR](/docs/nextjs/page-routing/switching-to-ssr). -You must use the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). You can choose the initial fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): - -``` -jss create my-first-jss-app nextjs --fetchWith REST -``` - -> Tracking and Analytics is currently not supported with the Sitecore GraphQL "Edge" schema. +### Layout Service requests Sitecore Layout Service requests must: -1. have tracking enabled (see [`tracking` parameter](/docs/fundamentals/services/layout-service#using-the-layout-service)), and -2. perform [header passing](/docs/nextjs/tracking-and-analytics/overview#header-passing) +1. Have tracking enabled (see [`tracking` parameter](/docs/fundamentals/services/layout-service#using-the-layout-service)). +2. Perform [header passing](/docs/nextjs/tracking-and-analytics/overview#header-passing). Both of these **are taken care of** using the `RestLayoutService` included with the Next.js SDK (part of the `@sitecore-jss/sitecore-jss-nextjs` npm package). > The Next.js sample app uses the `RestLayoutService` in the `SitecorePagePropsFactory`. See [`src/lib/page-props-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/page-props-factory.ts) for details. -The `RestLayoutService` will track layout requests and perform header passing by default, so there is no extra configuration required. However, tracking can be disabled with the optional `tracking` parameter, so ensure this hasn't been specifically set to `false`. For example: +The `RestLayoutService` will track layout requests and perform header passing by default, so there is no extra configuration required. + +Tracking can be disabled with the optional `tracking` parameter, so ensure this hasn't been specifically set to `false`. For example: ```javascript this.layoutService = new RestLayoutService({ From 145330c0cc17a84cfdf7f732d26da7439805ef45 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 22 Mar 2021 11:12:30 +0100 Subject: [PATCH 11/17] Re-work intro, adjust heading levels --- .../nextjs/tracking-and-analytics/configuration/en.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md index 790d9a4844..74d7c0ce13 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md @@ -11,21 +11,18 @@ This topic will guide you through the steps required to enable full Sitecore tra > Note this is different than *client-side tracking* via the JSS tracking API, which is possible for *both Static Site Generation (SSG) and Server-side Rendering (SSR)*. Please see the [JSS Tracking](/docs/fundamentals/services/tracking) page for details. -## Next.js application - -### SSR & REST only - JSS supports tracking and analytics only for server-side rendered applications using the REST fetch method. You can not currently use Tracking and Analytics with the Sitecore GraphQL "Edge" schema. -**Pre-requisites** +## Pre-requisites + - The application uses the SSR pre-rendering form. - The application uses the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service). -> You can choose the pre-rendering form and the fetch method when creating the project with the JSS CLI. For details, consult the [JSS CLI reference](/docs/fundamentals/cli). +> You can choose the pre-rendering form and the fetch method when creating the project with the JSS CLI. For details, consult the [JSS CLI reference](/docs/fundamentals/cli). > If your application currently uses SSG, you can [switch the `[[..path]].tsx` route from SSG to SSR](/docs/nextjs/page-routing/switching-to-ssr). -### Layout Service requests +## Layout Service requests Sitecore Layout Service requests must: From e75bf6b691185405fa5ac45c6c3892f4faa4b4a5 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 22 Mar 2021 11:34:17 +0100 Subject: [PATCH 12/17] Drop parens --- docs/data/routes/docs/fundamentals/cli/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/fundamentals/cli/en.md b/docs/data/routes/docs/fundamentals/cli/en.md index cf5e347dfa..eaa5879313 100644 --- a/docs/data/routes/docs/fundamentals/cli/en.md +++ b/docs/data/routes/docs/fundamentals/cli/en.md @@ -21,7 +21,7 @@ jss create |Parameter| Options | Description| Default |Template| |--- | --- | --- | --- | --- | -|`fetchWith` | `REST` or `GraphQL` | Specifies how the applicaiton should fetch Sitecore data (layout, dictionary). | `REST` | nextjs | +|`fetchWith` | `REST` or `GraphQL` | Specifies how the applicaiton should fetch Sitecore layout and dictionary data. | `REST` | nextjs | |`prerender` | `SSG` or `SSR` | Specifies the Next.js pre-rendering form for the primary `[[...path]].tsx` route. | `SSG` | nextjs | |`repository` | A repository: githubusername/reponame | Specifies which repository to use for creating the JSS app | `Sitecore/jss` | all | |`branch` | A branch name | Specifies which branch to use for creating the JSS app | `master` | all | From 62925af35f37ab1d04eae947951629acb58ef0ac Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 22 Mar 2021 11:34:46 +0100 Subject: [PATCH 13/17] Change wording --- docs/data/routes/docs/nextjs/data-fetching/data-services/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md index a7205be202..1f4458c622 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/data-services/en.md @@ -17,7 +17,7 @@ Next.js uses different data fetching strategies for each pre-rendering form. ## JSS Next.js data fetching -The JSS Next.js sample application includes usage examples for both data fetching strategies available in Next.js, as follows: +The Next.js-based JSS sample application includes usage examples for both data fetching strategies available in Next.js, as follows: * [`src/pages/[[..path]].tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.tsx) implements `GetStaticPaths` and `GetStaticProps` (SSG). * [`src/pages/[[..path]].SSR.tsx`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/pages/%5B%5B%2E%2E%2Epath%5D%5D.SSR.tsx) implements `GetServerSideProps` (SSR). From cde492cb749b392066b880d3560155dc88302edb Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Mon, 22 Mar 2021 11:35:56 +0100 Subject: [PATCH 14/17] Add CLI reference link, add headings for the switch sections --- .../switching-fetch-method/en.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md b/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md index 7bc4f5d0bb..510e224887 100644 --- a/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md +++ b/docs/data/routes/docs/nextjs/data-fetching/switching-fetch-method/en.md @@ -9,20 +9,19 @@ The Next.js sample application can use either the Sitecore Layout Service REST A > See [Layout Service API reference](/docs/fundamentals/services/layout-service) and [Dictionary Service API reference](/docs/fundamentals/services/dictionary-service) for more information. -You can choose the initial dictionary and layout data fetch method on create with the optional `fetchWith` parameter. REST is used by default if you omit the parameter. For example, [with `jss create`](/docs/nextjs/getting-started-nextjs/walkthrough-jsscreate): +You can change the data-fetching method after project creation. -``` -jss create my-first-jss-app nextjs --fetchWith {REST|GraphQL} -``` - -However, you may wish to switch the fetch method after creation. +## From REST to GraphQL To switch the Next.js sample application from REST to GraphQL: -1. Move or delete `\lib\dictionary-service-factory.ts` -2. Download [`dictionary-service-factory.graphql.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/dictionary-service-factory.graphql.ts) to `\lib\` and rename as `dictionary-service-factory.ts` +1. Move or delete `\lib\dictionary-service-factory.ts`. +2. Download [`dictionary-service-factory.graphql.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/dictionary-service-factory.graphql.ts) to `\lib\`. +3. Rename as `dictionary-service-factory.ts`. + +## From GraphQL to REST To switch the Next.js sample application from GraphQL to REST: -1. Move or delete `\lib\dictionary-service-factory.ts` -2. Download [`dictionary-service-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/dictionary-service-factory.ts) to `\lib\` \ No newline at end of file +1. Move or delete `\lib\dictionary-service-factory.ts`. +2. Download [`dictionary-service-factory.ts`](https://github.com/Sitecore/jss/blob/master/samples/nextjs/src/lib/dictionary-service-factory.ts) to `\lib\`. \ No newline at end of file From 27cedba67b73301b3570ebaf35749351bee04450 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Wed, 24 Mar 2021 09:31:22 +0100 Subject: [PATCH 15/17] Change case for consistency --- .../docs/nextjs/tracking-and-analytics/configuration/en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md index 74d7c0ce13..8631187587 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md @@ -11,7 +11,7 @@ This topic will guide you through the steps required to enable full Sitecore tra > Note this is different than *client-side tracking* via the JSS tracking API, which is possible for *both Static Site Generation (SSG) and Server-side Rendering (SSR)*. Please see the [JSS Tracking](/docs/fundamentals/services/tracking) page for details. -JSS supports tracking and analytics only for server-side rendered applications using the REST fetch method. You can not currently use Tracking and Analytics with the Sitecore GraphQL "Edge" schema. +JSS supports tracking and analytics only for server-side rendered applications using the REST fetch method. You can not currently use tracking and analytics with the Sitecore GraphQL "Edge" schema. ## Pre-requisites From b0ffd5bf87f84aba170be3ca1b311f71b284e65f Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Wed, 24 Mar 2021 09:32:29 +0100 Subject: [PATCH 16/17] Add note about visitor consent for tracking --- .../docs/nextjs/tracking-and-analytics/configuration/en.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md index 8631187587..5ac29c7e2b 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/configuration/en.md @@ -42,7 +42,9 @@ this.layoutService = new RestLayoutService({ ... tracking: false, // <-- disables tracking! }); -``` +``` + +> You might want to [Enable or disable web tracking based on visitor consent](https://doc.sitecore.com/developers/101/sitecore-experience-platform/en/enable-or-disable-web-tracking-based-on-visitor-consent.html). ## Sitecore configuration From 5cafd0be5555608475247dd639bc56334ff99b09 Mon Sep 17 00:00:00 2001 From: Anca Emcken Date: Wed, 24 Mar 2021 09:34:02 +0100 Subject: [PATCH 17/17] Change heading --- .../routes/docs/nextjs/tracking-and-analytics/overview/en.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md b/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md index 2f56970fc0..e498f5e068 100644 --- a/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md +++ b/docs/data/routes/docs/nextjs/tracking-and-analytics/overview/en.md @@ -1,9 +1,9 @@ --- name: overview routeTemplate: ./data/component-templates/article.yml -title: Overview and architecture +title: Overview --- -# Tracking & Analytics Overview and Architecture +# Tracking and Analytics Overview Sitecore analytics and personalization functionality is possible with Next.js only on SSR (Server-side Rendered) page routes using the [Sitecore Layout Service REST API](/docs/fundamentals/services/layout-service).