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 use...
Post a Comment
Read more

Troubleshooting 'System.Web.Mvc' Error During Sitecore Visual studio solution Publishing

  In my most recent blog, I extensively covered the steps involved in configuring a Visual Studio Solution for Sitecore development . Following the publishing process, I came across an error message that read " could not load file or assembly 'system.web.mvc, version=5.2.4.0 ," as visibly shown above. The root of the problem was traced back to a discrepancy between my Visual Studio solution, which was utilizing version 5.2.7.0 of  'system.web.mvc,' and the Sitecore Instance, which was employing version 5.2.4.0. To successfully address this issue,  I adopted a straightforward solution:  Copied the ' system.web.mvc.dll ' and ' system.web.mvc xml'  from my backed-up " C:\inetpub\wwwroot\sc103sc.dev.local - Copy\bin" folder.  Pasted to Visual Studio solution " C:\Users\ilma\source\repos\MySitecoreDemo\MySitecoreDemo\bin " and updated the solution Reference for the same. Also pasted to current Sitecore Instance ' bin folder  C:\i...
Post a Comment
Read more