1. Sitecore JavaScript Services SDKs (JSS) 22.x

Node XM Cloud Proxy

Version:

The JSS Node.js-based proxy app is the backbone for enabling seamless integration between SitecoreAI and various SPA frameworks like React, Angular, and Vue. At launch, it supports the JSS Angular starter kit, and it will lay the foundation for future JSS starter kits built for other front-end JavaScript frameworks. It acts as a middleware layer to handle critical functionalities such as server-side rendering (SSR), and to enable editing and personalization, A/B/n component testing, and Sitecore Forms integration.

By serving as the rendering host, the proxy ensures a smooth connection between SitecoreAI services and your front-end applications, making it easier to build dynamic, personalized, and localized experiences for users.

Note

The XM Cloud Proxy is in public beta. If you encounter any issues or bugs, please submit a new issue in the JSS GitHub repo.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

This is a sample setup showing how you can configure SitecoreAI rendering server on top of Node.js and Express.js

Note

The proxy does not support deployment to Vercel.

Getting started

Here are the main configurations defined in the config.ts file in the node XM Cloud proxy app:

  • Server bundle configuration:

    • The app loads a server.bundle.js file, pre-built from your SPA.

    • This file contains the required configuration options.

  • GraphQL endpoint setup:

    • Defines a graphQLEndpoint for handling Sitecore GraphQL requests. It differentiates between production (Sitecore Edge) and development (Sitecore CM) endpoints.

    • Constructs the target URL and path for proxy requests, ensuring compliance with http-proxy-middleware requirements.

  • Port configuration:

    • Configures the port for running the proxy, with a default of 3000 or an environment-specified port.

  • Personalization configuration (personalizeConfig):

    • Sets up Sitecore personalization through PersonalizeConfig, defining settings for both Sitecore Experience Edge and CDP endpoints.

    • Contains options to control personalization features, including:

      • Timeouts for Edge and CDP endpoints (default 400ms, configurable via environment variables).

      • Scope and site name used for Sitecore Personalize.

      • Enable/Disable Switch - functions that allow you to conditionally disable personalization based on the environment (such as disabling it in development mode) and and cookie consent policy.

      • Language configuration - defaultLanguage serves as a fallback if language data is unavailable in layout data.

This configuration is designed to be flexible and secure, with dynamic settings managed via environment variables where appropriate.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

Environment variables

The following environment variables can be used to configure the Node XM Cloud Proxy app instead of modifying config.js. You can use the .env file located in the root of the app, or you can set these directly in the environment (for example, in containers).

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

Parameter

Description

PROXY_BUNDLE_PATH

Path to the JSS SPA app's server.bundle.js. The default value is set in config.ts.

PROXY_PORT

Optional. Port used when you start the sample app. The default value is set in config.ts.

DEBUG

Optional. Debug level for the proxy. To see all logs, set the DEBUG environment variable to:

'sitecore-jss:,proxy,http-proxy-middleware*, 'sitecore-jss:layout','sitecore-jss:personalize'

JSS_EDITING_SECRET

Required when working with the Sitecore Editor to secure the /api/editing/render endpoint exposed by your proxy app. An alphanumeric value of at least 16 characters is recommended.

PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT

Optional. Timeout (ms) for Sitecore CDP requests to respond within. Default is 400.

PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT

Optional. Timeout (ms) for Sitecore Experience Edge requests to respond within. Default is 400.

Build and deploy a Node Proxy app for XM Cloud

Deploying a JSS application allows it to be used as an editing host in SitecoreAI. SPAs support SitecoreAI out of the box.

The following walkthrough describes how to:

  1. Run your application

  2. Deploy your application to Netlify

Note

It is not currently possible to deploy Node Proxy apps to Vercel.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

Before you begin

  • Build your SPA bundle with jss build or npm run build, and place the output in the dist folder.

Run your application

To run your application:

  1. Run npm install.

  2. Run npm run start.

Deploy your application to Netlify

To deploy your application to Netlify:

  1. In the parent directory of your Node XM Cloud Proxy app (which also contains your SPA), do the following:

    XM Cloud is now SitecoreAI

    Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

    1. Run npm init.

    2. In the resulting package.json file, add the following:

      "build": "cd ./<PROXY_APP_NAME> && npm run build-all && cd ..",
"install": "cd ./<PROXY_APP_NAME> && npm install && npm run install-all && cd ..",
      Important

      In all code samples, make sure you replace {:placeholder-token:}placeholders{/:placeholder-token:} with the actual values for your apps.

  2. Make sure your <PROXY_APP_NAME>/package.json file includes the following commands for handling the build and install steps:

    "build-all": "cd ../angular && npm run build && cd ../<PROXY_APP_NAME> && tsc",
"install-all": "cd ../angular && npm i && cd ../<PROXY_APP_NAME>"

  3. Configure serverless-http as follows:

    1. Install the npm package by running the following command:

      npm i serverless-http

    2. In your <PROXY_APP_NAME>/src/index.ts file, add the following import and export statements:

      import serverless from 'serverless-http';
...
export const handler = serverless(server);

  4. Create a netlify.toml file and add the following Netlify configurations to it:

    • This part allows the proxy app to be treated as Netlify functions:

      [functions]
directory = "<PROXY_APP_NAME>/src"
node_bundler = "esbuild"
included_files = ["<PROXY_APP_NAME>/dist/**"]

    • This part might be required to ensure static assets can be properly accessed:

      [[redirects]]
from = "/dist/browser/*"
status = 200
to = "/browser/:splat"

    • By default, redirects aren't applied if there's a file with the same path as the one defined in the from property. If you set force to true, the redirect rule will take precedence over existing files. For example:

      [[redirects]]
from = "/*"
status = 200
to = "/.netlify/functions/index/:splat"
force = true

    • This is the required build command:

      [build]
command = "npm run build"
publish = "<PROXY_APP_NAME>/dist"

  5. Create your Netlify deployment as follows:

    1. Configure all necessary environment variables, such as SITECORE_EDGE_CONTEXT_ID, SITECORE_SITE_NAME, and so on.

    2. In your site settings, on the Build and Deploy tab, configure your build settings. The following is a sample configuration:

      Field

      Value

      Base Directory

      /

      Build command

      npm run build

      Publish directory

      /proxy/dist

      Functions directory

      /proxy/src

    Note

    If Netlify doesn't recognize /proxy/dist as your publish directory, make sure that your PROXY_BUILD_PATH environment variable uses a Unix-style format such as ../proxy/dist.

If you have suggestions for improving this article, let us know!