Deploy your front-end application to Netlify

Netlify is a cloud computing company that offers a development platform that includes build, deploy, and serverless backend services for web applications and dynamic websites. Netlify has first-class support for Next.js.

This walkthrough describes how to:

  • Prepare for the deployment.

  • Set up continuous deployment for the Next.js JSS app on Netlify.

  • Configure webhooks to redeploy the app with updated content.

After completing this walkthrough, your application will automatically redeploy when you publish new items or merge/push code changes to your Git repository.

Prepare for deployment

Before deploying your Next.js JSS app to Netlify, you must ensure you have all the necessary environment variables ready and all the changes you want to deploy pushed in the repository and the branch you want to use for the deployment.

To prepare for the deployment of an application that uses GraphQL and Edge for fetching content and layout data:

  • If you made code changes in your local development environment, commit and push your code. If you set up your XM Cloud environment to redeploy when pushing changes to the configured branch, allow the redeployment to complete.

  • If you made content and layout changes in a local XM environment, use the Sitecore CLI to publish your changes and verify that your content is on Edge.

  • In your XM Cloud instance, publish all the changes you want to make available on your website.

On Netlify:

  • Log in or sign up for an account.

In your Next.js application:

  • Commit and push your changes to your Git repository.

Set up continuous deployment (CD) for the Next.js JSS app on Netlify

To automatically deploy your front-end application when you push changes in your repository, you must create a Netlify site, and configure the build process and environment variables. In this scenario, we assume you are deploying the Next.js application from the XM Cloud project repository, which includes the XM instance and the front-end solution.

To set up the automatic deployment of the Next.js application to Netlify:

  1. In your Netlify account, follow the Netlify documentation for adding a new site based on an existing repository. Choose a different branch if you don't want to deploy the application from your default branch.

  2. In the Build settings section, in the Base directory field, enter the path to the root folder of the Next.js application. When using the Next.js XM Cloud foundation template, the path is src/sxastarter.

    Netlify tries to populate additional fields based on your base directory. Verify that the auto-completed values are as follows:

    • Publish directory: src/sxastarter/.next.

    • Functions directory: src/sxastarter/netlify/functions. If you created custom serverless functions in a different directory, specify that directory here.

    • Build command: npm run build.

    For more information, see the Netlify Build configuration documentation.

  3. Click Add environment variables and enter the following variables:

    • SITECORE_EDGE_CONTEXT_ID - Your unified Context ID. Use the Preview Context ID for all content and layout data, or the Live Context ID for published data only.

    • SITECORE_SITE_NAME - the name of the site.

    • If you are building a very large website, enable retries for requests to the XM Cloud Experience Edge GraphQL endpoint, by setting the GRAPH_QL_SERVICE_RETRIES to a value higher than 0.

    • Any other custom environment variables you've added to your .env file. Netlify recommends that all environment variables be added to the Netlify site configuration.

      Note

      You don't need to set environment variables for Personalize and other Sitecore product integrations. They are included in your Sitecore Context and automatically provided to the application and integrations. An exception is Sitecore Search.

  4. Click Deploy site.

  5. When the Netlify deployment process finishes, verify that the deployed application hosted by Netlify renders as expected.

Troubleshooting the CD setup

At the end of the deployment process, even though Netlify reports that the site was successfully built and deployed, you may see a Netlify 404 error page instead of the expected pages.

The most likely reason is that, because of the nested location of the Next.js app in an XM Cloud project repository, Netlify could not detect that the application is a Next.js application and failed to set the correct runtime.

After your site is created in Netlify, in your Netlify dashboard, navigate to the site's configuration area and:

  1. In the Build & Deploy section, in the Build settings, click Configure.

  2. Find the Runtime setting and select Next.js.

  3. Redeploy the site.

Configure webhooks to redeploy the app with updated content

You can use webhooks to trigger automatic redeployments of your Next.js app when new data reaches the Edge Delivery Platform.

You register, update, remove, or list webhooks using the Experience Edge Admin API.

Note

Before using the Admin API for any operations, get an authentication token.

To trigger a new deployment on Netlify when your data reaches the Edge Delivery Platform:

  1. Create a build hook in Netlify and copy the URL of the build hook.

  2. Send a POST request to the Admin API webhook endpoint https://edge.sitecorecloud.io/api/admin/v1/webhooks with the following body:

    RequestResponse
    {
  "label": "My new webhook",
  "uri": "<your-netlify-build-hook-url>",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer: <edge-authentication-token>",
    "Content-Type": "application/json"
  }
}

  3. To verify the request was completed successfully, check that you received a 201 Created response status code.

  4. Make some changes in Sitecore and publish them.

The publishing process is complete when Experience Edge finishes processing the new data, and Netlify starts a new deployment.

Do you have some feedback for us?

If you have suggestions for improving this article,