JSS topologies

Current version: 19.x

JSS is a flexible technology that is designed to fit into most DevOps deployment processes. JSS sites can deploy in several different topologies. As a headless technology, if you are unsure of which to pick, lean towards a headless deployment to realize the maximum advantage of JSS.

Headless topology

In a headless topology, a traditional Sitecore XP (or XM) deployment is turned into an API server that serves content and layout data - with personalization pre-applied.


This topic does not cover how to configure Sitecore deployment outside of its interaction with JSS. There are Sitecore default deployment topologies outside of JSS.

The following diagram shows the request flow between the app users, JSS, and Sitecore when using the headless topology:

Sitecore JSS topology diagram

When running in headless mode, the Sitecore Content Delivery (CD) servers do not directly serve the public website. Instead, a cluster of inexpensive Node.js servers hosts the public-facing website. These Node servers run the node-headless-ssr-proxy. This server-side rendering (SSR) proxy makes requests to APIs running on the Sitecore CD servers and then renders the JSS application to HTML before returning it to the client. These SSR proxies can be hosted anywhere Node.js can run.

In the headless topology, you can use private Sitecore CD servers. The SSR proxies can also reverse-proxy specific paths, such as API calls and media library requests, to the Sitecore CDs. In this setup, the JSS app uses the proxy URL as its API server ( that is https://www.mysite.com), and the SSR proxy proxies to https://sitecore-cds.mysite.com.

You can avoid using the SSR proxy and serve static HTML files that the app fills in with API data. This removes the need for any Node hosting. However, when using client-only rendering some search engines might have trouble indexing your content: the HTML is largely blank without JavaScript execution. Some search engines do execute JavaScript with varying levels of success, but SSR is still a current best practice due to inconsistencies in how search engines handle JavaScript rendering.

Integrated topology

In an integrated topology, the Sitecore CD servers perform the server-side rendering of the JSS app using their own integrated (same server, out of process pool) Node.js services. This mode is less flexible in terms of scalability than a headless deployment, especially with regard to CDN integrations and the capability to scale API servers separately from SSR instances. In this mode, API hosting and rendering are performed on the same server.

There is also less flexibility to do advanced client-side routing scenarios when using integrated topology, as the requests are still pre-parsed by Sitecore and subject to Sitecore routing. In headless mode, you can run custom Express middleware to customize the server extensively. In integrated mode, similar customizations must be done in Sitecore (C#) instead.

The following diagram shows the request flow between the app users, JSS, and Sitecore when using the integrated topology:

Sitecore JSS integrated topology diagram

We do not recommend integrated mode for heavy load production scenarios, because the entire page is server-side rendered using Node.js as a block, not as individual renderings. Therefore, traditional output caching mechanisms become all-or-nothing. In other words, if caching is enabled, it forces caching of the entire page, which is almost always not what is desired.

Do you have some feedback for us?

If you have suggestions for improving this article,