Are you a Sitecore developer looking for ways to connect your headless application running locally from the XM Cloud environment as the editing host? Look no further than the tunnel command in Sitecore CLI. By utilizing this feature, you can easily connect your local application to the editing host in XM Cloud and streamline your development process.

In this article I will explain how to use the tunnel command to connect your local headless application as the editing host for the XM Cloud environment to make your development workflow more productive.

Requirements: You must have access to the XM Cloud environment for which you want to tunnel your headless application from your local system. If you do not have the access to XM Cloud environment then you must get it from your organization. Also you must have an headless site setup on the XM Cloud environment.

Assumptions: Here I assume that you are familiar and have hands-on experience with Next.js based JSS application. For the purpose of this article I will just use the JSS application but you can also use the XM Cloud code base as well.

Let’s star then.

Create the new JSS application, with nextjs template, using the following command, with appropriate app name matching with your XM Cloud headless site. Please make sure you answer Y for the Are you building for Sitecore XM Cloud? question, and select nextjs-sxa and nextjs-multisite add-ons. Refer the image given below.

npx create-sitecore-jss@latest

Once your application is created, download the ngrok.exe from ngrok site.

Extract the ngrok zip file and put the ngrok.exe file in the root directory of your headless application you just created in previous step.

Now you must register on ngrok website to get the auth token for ngrok to work through the tunnel command.

After registration and verifying your identity, open the ngrok dashboard and go to Your Authtoken page.

From the Your Authtoken page copy the ngrok config add-authtoken command given with authtoken for your account, and execute it in the terminal. Make sure you are in the root directory of the headless application where you placed the ngrok.exe file.

Now we need to setup the Sitecore.CLI for our application. If you are using the XM Cloud headless code base then you can skip the steps and jump over to the step for setting up the tunnel command.

Please note that all the commands are executed, in the terminal, are against the root folder of your headless application.

To use the Sitecore.CLI, first we need a new tool-manifest. Use the following command to initialize tool-manifest which will create the .config folder.

dotnet new tool-manifest

Now execute the following command to install Sitecore.CLI.

dotnet tool install Sitecore.CLI

After installing Sitecore.CLI, execute the following command to initialize the Sitecore.CLI configuration. The command will create .sitecore folder and sitecore.json file in the root directory of your headless application.

dotnet sitecore init

Now execute the following two command to add XMCloud and Tunneling plugins for the Sitecore.CLI

dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.XMCloud
dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.Tunneling

Now we need to authenticate against the XM Cloud environment for which we want to use the tunneling. Use the following command to login.

dotnet sitecore cloud login

Upon successful login you will be able to see similar information as shown in the below image in the .sitecore/user.json file for your application.

Now we need to connect the actual environment before staring tunnel. To connect to the environment we need the environment id from the XM Cloud Deploy app. If you have access to the XM Cloud Deploy app, then get the environment id and use the following command to connect to that environment.

dotnet sitecore cloud environment connect -id <environment-id> --allow-write true

If you do not have access to the XM Cloud Deploy app, use the following command to connect to the environment.

dotnet sitecore connect --ref xmcloud --cm <XMCLOUD CM HOST> --allow-write true -n default

Once done, you will be able to see following type of entry in the .sitecore/user.json file.

Please note host value in the JSON must be different for you based on your environment.

Now, we need to add the authority attribute like show below to make sure we do not get any errors while executing other commands.

Now, let’s setup the headless application.

Open the .env file and set the following environment variables.

JSS_EDITING_SECRET – Get the value from the <CM_HOST>/sitecore/admin/showconfig.aspx page. If you have not set the explicit value through the configuration patch file. The default value you will find is as follows:

<setting name="JavaScriptServices.ViewEngine.Http.JssEditingSecret" value="*** Key sitecore:cm:sitecorejsseditingsecret not found ***" patch:source="Sitecore.JavaScriptServices.ViewEngine.Http.config"/>

SITECORE_API_KEY – You must use the API key item ID from your XM Cloud CM. For example, see the below image.

SITECORE_API_HOST – Your XM Cloud CM host.

Please refer the below image.

Now, start the headless application in connected mode using the following command.

jss start:connected

Now, open a new terminal window and traverse to the root directory of your headless application.

Execute the following command. Replace the <HEADLESS_SITENAME> with your XM Cloud headless site name, and <ENVIRONMENT_NAME_IN_USER.JSON> with the environment name you want to connect. For me, it is jatin-training, for you it must be different based on the name you gave in the previous steps.

dotnet sitecore tunnel create --site <HEADLESS_SITENAME> --port 3000 -n <ENVIRONMENT_NAME_IN_USER.JSON>

In the terminal you will see information about the ngrok tunnel startup and information about the rendering host item created by the tunnel command.

The tunnel command also opens the ngrok terminal window which will show the requests handled through ngrok.

Now open the content editor and expand the Rendering Hosts node (/sitecore/system/Settings/Services/Rendering Hosts). You will see the rendering host item created by tunnel command.

The same rendering host item is also associated with your headless site which you can check by opening the site item node.

Now open any of the existing page in Experience Editor to check if it works well or not. If you have followed all the steps carefully, you will see the Experience Editor opens the page in edit mode.

You will also see the requests logged in the ngrok terminal as shown below.

I hope my article will help you to setup and use the Sitecore.CLI tunnel command for your development work.

Happy Sitecore learning!!!