XM Cloud - Deploy Headless App with Netlify CLI

Summary

We had a requirement to deploy code from a private repository in Azure DevOps to both Sitecore XM Cloud and Netlify. Netlify allows users to integrate natively with Azure Devops (opens in a new tab) as well as leverage their CLI (opens in a new tab) to do a deployment.

In this blog post, we will focus on how to leverage the Netlify CLI to deploy our headless application. For this example, we are using the Sitecore XM Cloud Starter Repository (opens in a new tab), which comes with a Sitecore JSS SXA Headless Next.js application.

In a previous blog post (opens in a new tab), we discussed how we leveraged the Sitecore CLI to deploy to XM Cloud. We won't dive into the XM Cloud specifics here, but please check that post out if you are interested.

The Solution

The headless application requires a netlify.toml file. This is a file-based configuration that specifies how Netlify builds and deploys your site. You can read up more on it here (opens in a new tab). We have added the command we use to build our headless application as well as the netlify plugin we use. Our use case is a simple one, but more configurations can be added.

In the source of your headless application, src/app, add a netlify.toml file with the following:

[build]
command = "npm run next:build"
publish = ".next"

[[plugins]]
package = "@netlify/plugin-nextjs"

From the root of your headless application, src/app, run the following commands:

npm install -g netlify-cli
netlify init --manual

Select Create & Configure a new site, then select your team and then finally enter in a site name. Navigate to the Sites page in your Netlify account and select your newly created site and copy the site id and save for later.

Next, we need to create an new authorization token. Navigate to the Netlify User Applications page (opens in a new tab) and select new access token. Make note of this token.

Next, run the following commands with the authorization token and site id:

npm run build
netlify deploy --build --site $env:NETLIFY_SITE_ID --auth $env:NETLIFY_AUTH_TOKEN --prod

Now, we can commit our package.json and our netlify.toml file and put the following in our Azure DevOps pipeline:

npm install -g netlify-cli
npm install
npm run build
netlify deploy --build --site $env:NETLIFY_SITE_ID --auth $env:NETLIFY_AUTH_TOKEN --prod

Troubleshooting

In our case we did hit some bumps with some dependencies. We had to make sure our package.json had the following dependencies:

  "dependencies": {
    "@netlify/blobs": "^6.3.1",
    "@netlify/next": "*",
    "@netlify/plugin-nextjs": "^4.41.3"
  },

It is also worth pointing out that we used Node 18.17.1 for this project. We did try with Node 20.x and saw the same behavior.

Conclusion

Netlify makes it easy for developers to get their applications deployed and live. We can leverage native integrations to our code base or use the flexible CLI. This allows us the ability to address unique business requirements and choose the right solution for our project.