Routing and page composition in JSS Next.js apps

Version: 21.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.

Configure display name based routing

JSS SDK versions 22.9 and higher support display name based routing. Display name based routing derives URLs from the display name field of Sitecore items instead of their item name field, providing more flexibility in creating user-friendly and localized URLs.

Note

This is currently supported only with SSR. SSG support is not available yet as it requires significant architectural changes.

Generate sitemaps for display name based routes

For generating sitemaps for display name routes you need to use a patch file to customize your Sitecore configuration.

To generate sitemaps for display name based routes:

  1. Add a customized localized class to the linkManager configuration.

  2. Make sure to set the useDisplayName attribute to true in the configuration as shown:

  3. Use the following sample patch file as a reference:

    RequestResponse
    <?xml version="1.0" encoding="utf-8"?>
<configuration>
<sitecore>
    <linkManager defaultProvider="switchableLinkProvider">
        <providers>
            <add name="customLocalizedProvider" type="Sitecore.XA.Foundation.Multisite.LinkManagers.LocalizableLinkProvider, Sitecore.XA.Foundation.Multisite" cacheExpiration="5" addAspxExtension="false" alwaysIncludeServerUrl="false" encodeNames="true" languageEmbedding="never" languageLocation="filePath" shortenUrls="true" useDisplayName="true" />
        </providers>
    </linkManager>
</sitecore>
</configuration>

  4. Re-deploy your environment.

  5. Open the Content Editor and go to your site in the Content tree.

  6. Go to Settings > Sitemap, and under the URL options section, update the Link provider name with the same class name in your custom patch config.

Note

After deploying the patch, sitemaps will only be generated for display name–based routes. Standard item name–based routes will no longer appear in the sitemap.

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.

Important

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.

Do you have some feedback for us?

If you have suggestions for improving this article,