Connect your JSS app to XM Cloud

Version: 22.x

After creating your application, you need to connect it to your XM Cloud instance before you can use it for local development. To do this, you need to add some environment variables to your app that are associated with the site you want to work with.

Warning

When you add sensitive data like this to your app, we strongly recommend you use a private file such as .env.local instead of .env to prevent the data being pushed into a remote repository where unintended audiences can access it.

Tip

If you want to connect your app to a different environment, site, or context later, you can repeat this process to alter the environment variables as often as needed.

This walkthrough describes how to:

  1. Locate the values for your XM Cloud environment

  2. Add the environment variables to your local app

  3. Test the connection between your app and XM Cloud

Before you begin

Locate the values for your XM Cloud environment

You can find the values you need to connect your app to XM Cloud on the environment's Developer settings tab.

To locate the values for your XM Cloud environment:

  1. On the Sitecore Cloud portal, click your project.

  2. On the right-hand side of the page, in the XM Cloud tray, click Open app.

  3. In the main toolbar, in the drop-down list for your project, click Manage environments.

  4. On the Projects page, in the Environments tab, click the name of the environment you want to connect your app to.

  5. On the Developer settings tab, in the Environment variables section, do the following:

    • In the Site drop-down list, click the name of the site you want to work on in your local app.

    • Use the JSS versions switch to specify whether your app is based on JSS version 21.6 or later, or on version 21.5 or earlier.

    • If your app is based on JSS 21.6 or later, use the Context switch to choose whether to connect to your site's Preview context or to its Live context.

  6. In the code block at the bottom of the Environment variables section, click Copy to clipboard.

Add the environment variables to your local app

Adding the relevant details to your app will enable it to connect to your XM Cloud repository and work on the chosen site.

To add the environment variables to your local app:

  1. In your JSS app's folder (such as /headapps/nextjs-starter/ , the default location for Next.js JSS apps), create a new .env.local file.

  2. Open the new file in your preferred IDE and paste the variables you copied to your clipboard in the previous section.

  3. Save your changes.

Test the connection between your app and XM Cloud

Now that you've connected your app to XM Cloud, you can test the connection by attempting to run and open the app locally.

To test the connection between your app and XM Cloud:

  1. Have a terminal window open with your JSS app's folder selected (such as /headapps/nextjs-starter/).

  2. If you've made any changes to your initial app's dependencies, including pulling changes from the remote repo, run the following command:

    RequestResponse
    npm install

  3. Run the following JSS CLI command::

    RequestResponse
    jss start:connected

  4. When the app has finished compiling, open the local host for your app (by default, this is http://localhost:3000) in a browser window.

    If you see the default landing page for your site, the app has connected successfully.

Do you have some feedback for us?

If you have suggestions for improving this article,