---
title: "Routing and page composition in JSS Next.js apps"
slug: "routing-and-page-composition-in-jss-next-js-apps"
abstract: "Overview of routing in multilingual JSS Next.js apps"
---
# Routing and page composition in JSS Next.js apps

Next.js comes with a file-system-based router built around the concept of [pages](https://nextjs.org/docs/basic-features/pages) and includes [advanced dynamic routing](https://nextjs.org/docs/routing/dynamic-routes).

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](https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes) defined in the file `/src/pages/[[...path]].tsx` that helps JSS Next.js [compose and render pages based on Sitecore data](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/page-composition-in-jss-apps-using-sitecore-data.html "Page composition in JSS apps using 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](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/nextjs-sitecore-routing.svg)

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](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/layout-service.html "Layout Service") or [Sitecore GraphQL Edge schema](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/the-experience-edge-schema.html "The Experience 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](https://doc.sitecore.com/xp/en/developers/104/platform-administration-and-architecture/en/use-a-patch-file-to-customize-the-sitecore-configuration.html).

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:

    ```xml
    <?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](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/routing-and-page-composition-in-jss-next-js-apps.html "Routing and page composition in JSS Next.js apps") apps but introduces an additional locale/language dimension to the routing process.

Next.js has built-in support for [i18n routing](https://nextjs.org/docs/advanced-features/i18n-routing). When you [configure i18n in your JSS Next.js](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/internationalization-in-the-jss-sample-app-for-next-js.html "Internationalization in the JSS sample app for Next.js") application:

- The `context` object contains the Next.js route `locale`.
- The [Layout Service](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/layout-service.html "Layout Service") receives the `locale` through the `sc_lang` parameter.

To [transition between locales](https://nextjs.org/docs/advanced-features/i18n-routing#transition-between-locales), you use the `Link` component from the `next/link` module or the `next/router`module.

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](https://nextjs.org/docs/advanced-features/i18n-routing#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](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/walkthrough--exporting-a-jss-next-js-app-to-static-html-files-with-next-export.html "Walkthrough: Exporting a JSS Next.js app to static HTML files with next export") you must disable localization.