Skip to main content

Step by step guide to Establish Headless SXA Tenant, Site and Next.js app with Sitecore XP 10.3

 

Step 1: Prerequisites

  • Installed Sitecore version 10.3 Check out Sitecore XP 10.3 Installation guide
  • Configured an HTTP binding in IIS for your site (e.g., http://demo.dev.local - Next.js requires specific setup to connect to an HTTPS server)
  • Installed Sitecore Powershell
  • Installed Sitecore Headless Services Checkout Headless Services Installation guide
  • Installed SXA 10.3
  • Successfully populated Solr schema and built necessary indexes
  • Ensured that you are running the latest version of Node

Step 2: Create a Headless Tenant

  1. Go to the Sitecore Launchpad and click on 'Content Editor' button.
  2. To create a Headless Tenant, right-click on the 'sitecore\content' and then choose 'Insert' > 'Headless Tenant'.
  3. Input the Tenant Name (for eg, 'HeadlessSXATenant'), choose all modules, and then click 'OK'.

  4. To create a Headless Site, right-click on 'sitecore\content\HeadlessSXATenant' and then select 'Insert' > 'Headless Site'.
  5. In the General tab, set our site's name to "HeadlessSXAsite"
  6. In the Modules tab, choose all the modules.
  7. On the Site Settings tab, you can keep the GraphQL endpoint as the default, and leave the Deployment secret field blank for now (we'll address this later).

  8. You will now observe the fundamental structure of your SXA-based website.

Step 3: Setting Up the Rendering Host for SXA

Sitecore requires information about the location of our Next.js front-end. This enables Sitecore to effectively act as a proxy for the site in Experience Editor and Preview modes, resulting in a seamless and impressive user experience.
  1. By default, the SXA site will reference the rendering host located at `/sitecore/system/Settings/Services/Rendering Hosts/Default`. The values should be configured as follows:
  • Rendering Engine Endpoint URL: http://localhost:3000/api/editing/render
  • Rendering Engine Application URL: http://localhost:3000
  • Application Name: HeadlessSXAsite (It should be same as site name)

2. To understand the connection of this configuration to your SXA site, you can view and modify the chosen rendering host at `/sitecore/content/HeadlessSXATenant/HeadlessSXAsite/Settings/Site Grouping/HeadlessSXAsite` within the Settings and Predefined Application Rendering Host section.

Step 4: Create JSS API Key

A brief setup step to establish an API Key for communication with Sitecore. It's worth noting that you can create multiple API Keys with various configurations, but in this instance, we'll create a basic one for development purposes.
  1. Go to /sitecore/system/Settings/Services/API Keys, right-click, and choose to Insert > API Key Enter the name (eg. NextjsKey) , press OK and Configure CORS Origin as '*' and Allowed Controllers as '*'..
  2. Retrieve the Item ID of the API Key, save it, and copy it to a notepad. This ID will be necessary for the upcoming JSS setup steps. Remember to save and publish the item. When using the API Key in the setup, omit the curly brackets but retain the dashes.

Step 5: Install Sitecore JSS CLI

Step 6: Initialize a JSS App

  1. Go to the directory where you've installed the Sitecore JSS CLI
  2. Execute the following command: npx create-sitecore-jss --templates nextjs,nextjs-sxa --appName HeadlessSXAsite --hostName sc103sc.dev.local --fetchWith GraphQL 
  • When prompted for the application location, simply leave it empty.
  • When asked how to prerender the application, choose SSG for static site generation.
  • Please keep in mind that we're building an application using the nextjs and nextjs-sxa app templates. The nextjs-sxa template will install the necessary code to enable the out-of-the-box Headless SXA components we previously installed.
  • Although --fetchWith GraphQL is actually the default setting, it's included here to emphasize that we're operating in *connected mode.
  The output should resemble the following:

Step 7: Configure the JSS app.

  1. To begin, let's move up to the directory of our freshly created Next.js application. This step is crucial because, with the application now established, this will serve as our new starting point for executing commands.
  2. Now, execute the command `jss setup`. This will generate the `/scjssconfig.json` file, which includes a substantial portion of the connectivity configuration for your application. Please refer to the image below for further details.
    1. Is your Sitecore instance on this machine or accessible via network share? [y/n]: y
    2. Path to the Sitecore folder (e.g. c:\inetpub\wwwroot\my.siteco.re): C:\inetpub\wwwroot\sc103sc.dev.local 
    3. Sitecore hostname (e.g. http://myapp.local.siteco.re; see /sitecore/config; ensure added to hosts): http://sc103sc.dev.local
    4. Sitecore import service URL [https://xp103.sc/sitecore/api/jss/import]: [Leave blank]
    5. Sitecore API Key (ID of API key item): 1BFBEF10-49FC-41A9-B09C-44CDF007C804 [Input the API key that was previously created, as outlined in the 'Create JSS API Key' section.]
    6. Please enter your deployment secret (32+ random chars; or press enter to generate one): [You can either leave this field blank, and it will automatically generate a deployment secret, or you can manually enter a value here]
    7. Take note of the highlighted values. Also, observe where the deployment secret is saved, which is at C:\Sitecore10\10.3\Headless\HeadlessSXAsite\sitecore\config\HeadlessSXAsite.deploysecret.config

Step 8: Concluding Configuration Adjustments in Next.js and Sitecore

  1. Eliminate Hardcoded Site Definition: Go to .\sitecore\config\HeadlessSXAsite.config and comment out the default site definition. This definition is managed by SXA configuration items within Sitecore, making it unnecessary.
  2. Confirm JSS App Registration: Examine the values of the serverSideRenderingEngineEndpointUrl and serverSideRenderingEngineApplicationUrl. These URLs should match the one configured in the rendering host and modify the Sitecore Path value.
  3. Open the .env file located in the root directory of your Next.js application. Locate the line containing JSS_EDITING_SECRET= (You can use Deployment secret ) and SITECORE_API_KEY= (You can use API Key GUID with brackets and dashes removed)
  4. Next, go to the .\sitecore\config\HeadlessSXAsite.config file and modify the value of the JavaScriptServices.ViewEngine.Http.JssEditingSecret setting to match the JSS_EDITING_SECRET you previously configured. (you'll need to uncomment this setting)
  5. Add RootItemId to DictionaryServiceFactory: Go to .\src\lib\dictionary-service-factory.ts, Insert the property rootItemId: {home-item-guid}. The rootItemId corresponds to the item ID of the Home item located at /sitecore/content/HeadlessSXATenant/HeadlessSXAsite/Home, which is the homepage of your SXA site.

Step 9: Deploy Configuration

    Run: jss deploy config
Please be aware: It is recommended to restart your IIS for safety. I've noticed that new configurations don't always trigger an IIS restart. For instance, when I inspected ShowConfig.aspx, my JSS Editing Secret didn't appear until after I performed a restart.

Step 10: Initiate the Application in Connected Mode

  • Run: $env:NODE_TLS_REJECT_UNAUTHORIZED=0
  • Run: jss start:connected
  • Access http://localhost:3000
  • A blank page is displayed because no components have been added yet.

Verify Experience Editor

Return to Sitecore, find your home item at /sitecore/content/HeadlessSXATenant/HeadlessSXAsite/Home, right-click on the item, and choose Experience Editor.

Check out my blog : Troubleshooting Sitecore Headless SXA & Next.js -  Error: GraphQL Error (Code: 404)

We're all up and running. Thanks for Reading!!😄

Comments

Post a Comment

Popular posts from this blog

Sitecore Interview Questions 2023

1. What Is a CMS? A content management system (CMS) is software that helps users create, manage, and modify content on a website without the need for technical knowledge.  2. What is Sitecore ? Sitecore is a versatile and powerful digital experience platform used by businesses and organizations around the world to create, manage, and personalize their online presence. At its core, Sitecore offers a Content Management System (CMS) that allows users to easily create, edit, and organize digital content for websites, mobile apps, and other online platforms without requiring extensive technical knowledge. However, Sitecore goes beyond traditional CMS capabilities. It's often referred to as a Customer  Experience Platform (CXP) due to its ability to not only manage content but also provide tools for personalization, analytics, and marketing automation. This means that with Sitecore, businesses can tailor the online experiences they offer to individual users, gather insights into user beh
Post a Comment
Read more

Set up Visual Studio MVC Solution for Sitecore development

  Prerequisites: Sitecore (I have used Sitecore 10.3 in this example) Visual studio (Visual studio 2019) with Sitecore installed .Net 4.8 Checkout  Sitecore compatibility table for Sitecore XP 9.0 and later Set up a Visual Studio project To set up a Visual Studio 2019 project for Sitecore MVC: Open Visual Studio 2019 as an Administrator and click Create a new project  In the Create a New Project dialog, add filter C#, Windows ,Web now scroll and Select ASP.NET Web Application and click on Next In the Configure your New Project dialog, write the Project name and make sure to select .Net Framework 4.8 then click on Create . In the Create a new ASP.NET Web Application dialog, select Empty and check MVC then click on Create .  Following structure will be created. Delete App_Start folder we will not use it.  Copy the  Global.asax   and Web.config file from the Website folder of the Sitecore installation. Now write click on the solution and click on  Open Folder in File Explorer o
Post a Comment
Read more