Tailwind Logo

XM Cloud Next.js Starter Kit Changes

Headless SXAXM Cloud

Published: 2024-10-01

With regard to the XM Cloud starter kit, information has emerged that it will replace the headless-first configuration. We would like to change the configuration of the repository, referring to this information.

Rob's blog covered it extensively, and for the original story, see the source below.

In addition, a YouTube video is up, and this is the point.

Major Changes

Until now, it has been assumed that the development environment would be run on hand using docker, but this will make it easier to develop in Headless.

authoring folder

It contains the data to be serialized and the tools needed in the editing environment. This is where the platform used to be located under src.

headapps folder

This contains the previous sxastarter samples, but the folder has been renamed nextjs-starter. This may be the first step to support various rendering methods including Nuxt and astro in the future.

local-containers folder

This is where you will find all the files related to Docker. It makes it easier to consolidate the many Docker-related files at the root level.

Of course, Docker for local use is a powerful tool, but I also build by connecting to XM Cloud instances, so I would like to get this change in place for the demo environment at hand first.

Reflect a set of new files

Copy auhtoring, headapps and local-containers from the newly provided template, which is a temporary duplicate.

xmdev01.png

Organizing Docker

The Docker in the repository I provide as my demo environment has the following customizations for the cm instance.

  • Apply xdt file to enable Content Hub DAM
  • Copy Japanese resources
  • Add a setting for langagefallback

The hierarchy of folders is as follows

xmdev02.png

Copy the above file to the new folder and rewrite the file local-containers\docker\build\cm\Dockerfile as follows

Dockerfile
# escape=`

ARG PARENT_IMAGE
ARG SOLUTION_IMAGE
ARG TOOLS_IMAGE

FROM ${TOOLS_IMAGE} as tools
FROM ${PARENT_IMAGE}

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

WORKDIR C:\inetpub\wwwroot

# Copy developer tools and entrypoint
COPY --from=tools C:\tools C:\tools

# Copy Localization Files
COPY .\App_Data \inetpub\wwwroot\App_Data

# Copy Config files - language fallback
COPY .\App_Config \inetpub\wwwroot\App_Config

# Copy Xdts
COPY .\Xdts\ .\Xdts

# Perform transforms
RUN (Get-ChildItem -Path 'C:\\inetpub\\wwwroot\\xdts\\web*.xdt' -Recurse ) | `
    ForEach-Object { & 'C:\\tools\\scripts\\Invoke-XdtTransform.ps1' -Path 'C:\\inetpub\\wwwroot\\web.config' -XdtPath $_.FullName `
    -XdtDllPath 'C:\\tools\\bin\\Microsoft.Web.XmlTransform.dll'; };

Then the docker-compose.yml and docker-compose.override.yml, previously in the root, had rendering added when adding Tailwind CSS's Next.js project. For the sake of simplicity, we will not reflect the additions this time around and leave it as is.

The customization around Docker is the part where the .env file is used as template and init.ps1 is generated from the template. This procedure is based on the following blog post.

After the above work is completed, delete the following files that are no longer needed.

  • .env.template
  • docker-compose.override.yml
  • docker-compose.yml
  • down.ps1
  • init.ps1
  • New-EdgeToken.ps1
  • up.ps1
  • upFunctions.ps1
  • A set of docker folders

Finally, the first time you start up, you will import Rendering host items using the Sitecore CLI, but this time the paths related to serialization have been changed. This configuration file is sitecore.json, so please change the path.

JSON
{
  "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",
  "modules": [
    "authoring/items/**/*.module.json"
  ],

The settings are now reflected in the new environment in one step. Now let's actually start the system.

PowerShell
.\local-containers\scripts\init.ps1 -InitEnv -LicenseXmlPath "C:\projects\license\license.xml" -AdminPassword "DesiredAdminPassword"

The .env file was successfully created. Next, XM Cloud running in a container is executed for the first time with the following command.

PowerShell
.\local-containers\scripts\up.ps1

After a short time, the XM Cloud container was running locally.

xmdev03.png

The sxastarter sample page could be opened in the Experience Editor.

xmdev04.png

update authoring folders

If we first look at the structure of the folder, we see that it contains data related to the traditional src^platform and serialization.

xmdev05.png

Since the sample you have contains exactly the changes you are making to the CM of the Docker container, copy the appropriate files. Also, just placing the files does not mean that they will be reflected in the build, so we will add the relevant files to the authoring\platform\Platform.csproj file.

The following are the items added this time.

XML
  <ItemGroup>
    <Content Include="App_Config\Include\zzz\languagefallback.config" />
    <Content Include="App_Data\items\core\localization\cmp.items.core.ja-JP.dat" />
    <Content Include="App_Data\items\core\localization\dam.items.core.ja-JP.dat" />
    <Content Include="App_Data\items\core\localization\items.core.ja-JP.dat" />
    <Content Include="App_Data\items\core\localization\items.core.jss.ja-JP.dat" />
    <Content Include="App_Data\items\core\localization\items.core.sxa.ja-JP.dat" />
    <Content Include="App_Data\items\master\localization\cmp.items.master.ja-JP.dat" />
    <Content Include="App_Data\items\master\localization\dam.items.master.ja-JP.dat" />
    <Content Include="App_Data\items\master\localization\items.master.ja-JP.dat" />
    <Content Include="App_Data\items\master\localization\items.master.jss.ja-JP.dat" />
    <Content Include="App_Data\items\master\localization\items.master.sxa.ja-JP.dat" />
    <Content Include="App_Data\localization\cmp.texts.ja-JP.xml" />
    <Content Include="App_Data\localization\dam.texts.ja-JP.xml" />
    <Content Include="App_Data\localization\texts.ja-JP.xml" />
    <Content Include="App_Data\localization\texts.jss.ja-JP.xml" />
    <Content Include="App_Data\localization\texts.sxa.ja-JP.xml" />
    <Content Include="xdts\Web.config.xdt" />
    <None Include="Platform.wpp.targets" />
    <None Include="Properties\PublishProfiles\Local.pubxml" />
    <None Include="README.md" />
    <None Include="web.config" />
  </ItemGroup>

This reflects the required data. Old files will be deleted.

  • src\platform set
  • XmCloudSXAStarter.sln
  • Packages.props
  • Directory.Build.targets

Finally, to reflect the data in the xsdt folder in XM Cloud, add the following to the xmcloud.build.json file

JSON
  "transforms": [
    {
      "xdtPath": "/xdts/",
      "targetPath": "/"
    }
  ],

This file is now ready to work with Content Hub DAM by adding CORS settings; Platform-related preparations are complete.

As for the sites introduced in the repositories on hand, since they contain demos in multiple languages, we always create items related to the Japanese language as a setting. So this time, I created the file authoring\items\sites-init.module.json as follows.

JSON
{
  "$schema": "../../.sitecore/schemas/ModuleFile.schema.json",
  "namespace": "sites-init",
  "items": {
    "includes": [
      {
        "name": "SystemLanguages",
        "path": "/sitecore/system/Languages/ja-JP",
        "scope": "singleItem"
      },
      {
        "name": "SystemLanguagesEnUs",
        "path": "/sitecore/system/Languages/en-US",
        "scope": "singleItem"
      },
      {
        "name": "core-SystemLanguages",
        "path": "/sitecore/system/Languages/ja-JP",
        "scope": "singleItem",
        "database": "core"
      },
      {
        "name": "StandardWorkflow",
        "path": "/sitecore/system/Workflows/Standard Workflow"
      }
    ]
  }
}

We created the required items and serialized them again to create the item data as well.

xmdev06.png

Modification of Sample Programs

Finally, move the tailwindcss folders you have created so far into the headapps folder. Also, since the sxastarter folder is no longer needed, you can delete the entire src folder.

Because the rendering is now used in a different location, we need to change two things: we need to change the path used by the Docker container for rendering, and we need to change the volumes in the file local-containers\docker-compose.override.yml to Change the file volumes in the local-containers\docker-compose.override.yml file to.

Dockerfile
  rendering:
    image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-rendering:${VERSION:-latest}
    build:
      context: ./docker/build/rendering
      target: ${BUILD_CONFIGURATION}
      args:
        PARENT_IMAGE: ${REGISTRY}${COMPOSE_PROJECT_NAME}-nodejs:${VERSION:-latest}
    volumes:
      - ../headapps/tailwindcss:C:\app

Next, rewrite the path in the xmcloud.build.json file so that it can be used in the same way when deployed to XM Cloud.

JSON
{
  "renderingHosts": {
    "xmcloudpreview": {
      "path": "./headapps/tailwindcss",
      "nodeVersion": "20.14.0",

This completes the change, and you should confirm that it works in both the Docker and XM Cloud environments.

Summary

In this presentation, we focused on changing an existing sample to a new project format. How to use the new project format will be introduced separately.

Tags