Tutorial: How to Create a Site and Connect your App

Overview

In XM Cloud, a site is a collection of one or more pages, and a page can have several components. Through this tutorial series we will be creating a new Company Dev site and building out pages and components for the site. You will use the XM Cloud tools and your local development environment to explore the creation of a new site.

In this tutorial you wil do the following:

1. Create a new site in XM Cloud
2. Download and initialize your Next.js application
3. Connect your Next.js application to your XM Cloud instance
4. Verify that your connection is working by changing some content and viewing the updated content in your Next.js application

Prerequisites

In order to complete the following tutorial, you will need these resouces:

1. A valid organization login for the Sitecore Cloud portal
2. The XM Cloud environment created in the Setup XM Cloud tutorial.
3. The GitHub repo created in the Setup XM Cloud tutorial.
4. An IDE such as Visual Studio (VS) Code.
5. A valid XM Cloud license file.

   If you haven't already downloaded a license file, refer to the docs on downloading your organization's license file from the portal.

Create the site

With the environment initially created, you can now create your first site in XM Cloud. This will verify that the authoring environment is working and you can start the base of your project that will be used in these tutorials.

1. To begin, open the Sitecore Cloud Portal (https://portal.sitecorecloud.io) and log in.

2. You can access XM Cloud via the XM Cloud Deploy app through the “Go to XM Cloud” button

   

   If you closed that screen already you can also access XM Cloud from the Sitecore Cloud Portal. Click the “Open app” button on the top right.

   

3. Under the Sites tab, click Create site.

   

4. In the New site step you will choose a site template. Choose Basic Site.

   You can choose to create an Empty Site, or a Basic Site that already has some content in it. When creating your own websites outside the scope of this tutorial or as a quick demo, we recommend using the Empty Site, as it requires less cleanup than the Basic Site template. However, for this tutorial, you will select to use the basic site.

   

5. Name the site Company Dev and select a pre-configured language, in this case, English.

   

   In the screenshot and in your dialog you will also see another option where you can select an existing Site identifier, or create a new one. This is required when connecting Sitecore CDP, the Customer Data Platform for embedded analytics and personalization. We will skip that step for now and start the creation process of the site.

6. Click Create site, which will scaffold the website in the background. This will take a few minutes.

   Once your site is scaffolded in the background, you can access it using XM Cloud Pages and start editing the content.

   

7. Click on the website, which opens up a WYSIWIG editor where you can begin to edit the content, see components that you can use to edit the site, and switch between languages and your sites (top navigation bar).

   

Download and initialize your Next.js app

You will now get your local application running and connected to XM Cloud. You will need to navigate to your GitHub account and download the repository that was cloned in the previous tutorial by the Sitecore XM Cloud Deploy App.

Download Repository

1. In your repositories overview, find the newly created xm-cloud-tutorial-series repo.
2. Download the repository to your local file system.
3. Open the newly created folder in VS Code, or your text editor of choice.
4. As per the README, run the init script that was delivered with your source code repository and pass the following parameters:
   • -LicenseXmlPath: the path to your XM Cloud license file
   • -AdminPassword: the admin password of your XM Cloud instance (“b”, in this case).

The init script initializes the .env file with everything necessary.

Connect the App to the XM Cloud Instance

As you may remember from the introduction in the previous tutorial, you need to use a GraphQL endpoint to query the content coming from XM Cloud. To connect to the endpoint, a few things need to be configured up front.

1. Navigate to the .env file within your solution under src\sxastarter, and copy it.

2. Name it .env.local. We do this so that the file is ignored by git by default, so that you do not pass valuable configuration secrets into any repositories.

You can connect using the delivery endpoint of Edge or to the preview endpoint of your CM instance.

Any app showing content to the public must connect to the Edge Delivery Endpoint that is scaled and geographically distributed to serve the right performance. Only published content will be available here. For development purposes, you will connect to the preview endpoint as you do not need to care about publishing at this point, so created content is instantly available. This will simplify the development workflow. If you want to learn more about endpoints and the edge delivery architecture, check out the docs on Experience Edge architecture

Now, you need to set the API key within .env.local. The API key should be already available within your XM Cloud instance.

1. Get the Context ID from XM Cloud by:

   • Go to the XM Cloud deploy app
   • Click on the name of the project you created e.g. XM Cloud Tutorial Series
   • Copy the value in the Context ID (Preview) column
   

2. Paste the value of the Context ID into the SITECORE_EDGE_CONTEXT_ID environment variable in the .env.local file.

   

3. Add the Site name (e.g. Company dev) to the SITECORE_SITE_NAME environment variable in the .env.local file.

   

4. In your terminal navigate to src/sxastarter (your app folder) and run npm install

   

5. Now run npm run start:connected

   

6. Call your app in the browser: http://localhost:3000

   

Verify the connection

Let’s change some content to verify you are in fact connected against the preview endpoint.

1. Navigate back to your site in XM Cloud.
   
2. Click on the tile that says Company Dev. This will open Pages new WYSIWYG page editing experience. When opening for the first time, this might take a moment.
3. Change the headline to whatever you like. In this case, I’ll add 'in town' to the homepage tagline.
   
4. Your changes are autosaved.
5. Switch back to the browser tab where you are viewing the Next.js app on http://localhost:3000
6. Reload the page, and see the changes appear in your local app.
   

Related XM Cloud Documentation

• Getting started with XM Cloud
• Create websites
• Design webpages
• Understanding components in XM Cloud
• Working with languages
• Working with Pages
• Publishing in XM Cloud
• JSS GraphQL API

Related XM Cloud Accelerate guidance for Sitecore Partners

• Creating a Site