Routing and state management in the JSS React app

Current version: 19.x

The sample app uses dynamic routing based on the Layout Service (or local route data files in disconnected mode) and uses route/navigation changes to trigger app state changes. Tracing the primary execution flow must begin with the route configuration.

Client-side routing

Starting from the main client-side entry point of the app in the src/index.js file, the following describes the flow of the client-side routing:

  • In the file src/index.js SSR data and state are gathered and passed on to the <AppRoot> component.

  • In the file src/AppRoot.js the router is configured to respond to app routes and pass them on to <RouteHandler>.

  • In the file src/RouteHandler.js, Layout Service data is acquired for the current route, and the route and language state of the app is maintained. Route data is passed off to the <Layout> component.

  • In Layout.js, the shell HTML and global elements of the JSS app, along with its root <Placeholder>(s) are rendered.

  • The remaining structure of the route is defined by the route data, which defines which components - and their content data - live in each placeholder.

Server-side routing

When the React app is prerendered by a Node server, it returns HTML to the client in the initial response. This means that the route data flow is similar to client-side routing but has a few key differences.

The following describes how the server-side route data flow differs from the client-side routing:

  • The first step varies based on application mode:

    • In integrated mode only, Sitecore receives the request, parses the route server-side, determines whether the requested item will be handled by a JSS application, and which bundle to execute if you have more than one JSS application deployed in Sitecore.

    • In headless mode only, the Node SSR proxy receives a request and passes it on to a Sitecore layout service.

  • The Node host invokes the renderView function in the server/server.js file. The function arguments include the route data / Layout Service output.

  • The renderView function performs the following steps:

    • Receives the layout and dictionary data to use when server-side rendering (SSR).

    • In the root component src/AppRoot.js, stores the SSR data in the app's initial state in the member sitecoreContext. This initial state is provided to the SitecoreContext component wrapping the application.

    • Renders the app to HTML using React's SSR capabilities.

    • Embeds the rendered app within its index.html template and sets metadata and the SSR state. The SSR state (window.__JSS_STATE__) is used to rehydrate the app state on the client, preventing the need to call Layout Service for initial route data.

    • Invokes the render callback function with the final HTML.


When using GraphQL, the sample app by default uses Apollo GraphQL tools to render the app to HTML on the renderToStringWithData() server. This allows server-side rendering with the async results of GraphQL queries evaluated. If you are not using GraphQL, you can use ReactDOMServer.renderToString() method instead.

Do you have some feedback for us?

If you have suggestions for improving this article,