Routing and page composition in JSS Next.js apps


How JSS routes to Sitecore with Next.js

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


Overview of routing in multilingual 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 locale is passed to the Sitecore Layout Service with the sc_lang parameter.

To transition between locales, you can 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 for the language prefix (sub-path route) to be returned 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.


The static HTML export process (using next/export or the JSS CLI command jss export) does not support multilingual apps. To export your application as static HTML files you must disable localization.