XDT Magic in Sitecore: Supercharging Your Content SDK Boilerplate

Hello everyone, In this blog we will learn and see an important concept i.e XDT transformation which is widely used in Sitecore ecosytem even if it is XP, SXA, Headless or Sitecore AI. Let's start quickly.

What is XDT tranformation:

Managing configuration changes across multiple environments can quickly become difficult. We might have many important credentails that may vary across your different environment like third party api url, credentials or even emails that can be triggered during workflow publishing. This are mostly run time configuration changes and this is mostly after deployment process.

I will mostly focus on Sitecore AI, By default we have transformation configuration node that can be added to xmcloud.build.json file. So when this config is available, during Sitecore AI deployment, it auto pickup the tranformation file and perform the transformation directly. Check the below screenshot which will give you fair idea.

Now let’s move on to the interesting part—how to implement this within a Content SDK boilerplate template. Before making any changes, it’s always best to validate everything locally. Since XDT support isn’t available out of the box in the Content SDK boilerplate, I’ll walk you through the steps you can follow to add it.

Step 1: Create XDT folder under platform project. Authoring --> Platform --> XDTS. Check the below image.

Step 2: Now add the transforms node in xmcloud.build.json file. You can find the screenshot above.

Step 3: Now add the below powerShell script to your up.ps1 file before docker pull command.

       
$platformXdts = Join-Path $RepoRoot "authoring\platform\xdts"
$customDir = Join-Path $RepoRoot "local-containers\docker\build\cm\custom\xdts"
if (-not (Test-Path $customDir)) {
    New-Item -ItemType Directory -Path $customDir -Force | Out-Null
}
if (Test-Path $platformXdts) {
    # copy recursively preserving the folder layout under xdts
    Get-ChildItem -Path $platformXdts -Recurse -File | ForEach-Object {
        $relative = $_.FullName.Substring($platformXdts.Length) -replace "^\\",""
        $dest = Join-Path $customDir $relative
        $destDir = Split-Path $dest -Parent
        if (-not (Test-Path $destDir)) { New-Item -ItemType Directory -Path $destDir -Force | Out-Null }
        Copy-Item $_.FullName -Destination $dest -Force
        Write-Host "Staged XDT: $($_.FullName) -> $dest" -ForegroundColor Green
    }
} else {
    Write-Host "[INFO] no platform xdts folder found at $platformXdts" -ForegroundColor Cyan
}       
	   

Now after this code is executed, it will create the needed folder under local-container --> docker --> build --> cm --> custom. Check the below screenshot.

Step 4: It's time to update the actual docker cm file image to use the custom xdt file and do the transformation during your cm container up.

       
# copy your XDT files into a temporary transform folder inside the image
COPY custom/xdts/ C:\transforms\

# use the Sitecore tooling from the tools image to apply the transforms
# here we demonstrate a file transform; adjust for folder if necessary
# Add this at the very top of your Dockerfile if it's not there already
# escape=`

RUN if (Test-Path C:\transforms) { `
        Write-Host 'Applying XDTs from C:\transforms to webroot'; `
        C:\tools\scripts\Invoke-XdtTransform.ps1 -Path C:\inetpub\wwwroot\web.config -XdtPath C:\transforms\Web.config.xdt; `
    }
	   

Note : You need to copy the transformation file to C:\transforms folder under your CM container. There are internal scripts which will take this file from C:\transforms folder and do the needful. This way, your local transformation will be working fine. Transformation will take effect only on cm container up. You can run it in detach mode. You can run docker compose up {cm container name} -d

Step 5: Verification. You can open your cm container and check the actual web.config file. You should see your transformation.

You can check my other blogs too if interested. Blog Website