Routing and page composition in JSS Next.js apps

Current version: 22.x

Next.js comes with a file-system-based router built around the concept of pages and includes advanced dynamic routing.

JSS uses the Next.js routing system in Next.js sample apps. When creating a JSS Next.js application, it is instantiated with an optional catch-all route defined in the file /src/pages/[[...path]].tsx that helps JSS Next.js compose and render pages based on Sitecore data.

The following diagram provides a high-level overview of the routing process in a JSS Next.js app:

Diagram of JSS Next.js routing process

When accessing a page in the browser, the optional catch-all route passes the path information to the data fetching method defined in the page, 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 and makes a request to the Sitecore Layout Service REST API or Sitecore GraphQL Edge schema to fetch layout data for the item.

Internationalized routing in JSS Next.js apps

Internationalized (i18n) routing works similarly to regular page routing in JSS Next.js apps but introduces an additional locale/language dimension to the routing process.

Next.js has built-in support for i18n routing. When you configure i18n in your JSS Next.js application:

  • The context object contains the Next.js route locale.

  • The Layout Service receives the locale through the sc_lang parameter.

To transition between locales, you use the Link component from the next/link module or the next/routermodule.

You can configure the <languageEmbedding> setting in Sitecore. The setting must be set to asNeeded or always to return the language prefix (sub-path route) from Sitecore internal links. The Link component provided by JSS for Next.js handles i18n route transitions for internal links coming from Sitecore.

JSS Next.js applications created based on the Next.js JSS sample app use sub-path routing by default. While Next.js supports domain routing, using this strategy in JSS Next.js apps requires custom implementation.

Do you have some feedback for us?

If you have suggestions for improving this article,