Walkthrough: Deploying your front-end application to Netlify

Version:

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 deployment.
Deploy the Next.js JSS app to Netlify.
Configure webhooks to redeploy the app with updated content.

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:

Generate an Edge API token if you don't already have one. You use this token to verify that your content is published to Edge and as a value for the SITECORE_API_KEY environment variable.
In your SitecoreAI instance, publish all the changes you want to make available on your website.

Note

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. If you also made code changes, commit and push your code. If you set up your environment to redeploy when pushing changes to the configured branch, allow the redeployment to complete.

On Netlify:

In your Next.js application:

Commit and push your changes to your GitHub repository.

Deploy the Next.js JSS app to Netlify

Before deploying the Next.js JSS app, we suggest you watch the following video, which guides you through the deployment process. In the video, the publishing is done from the SitecoreAI Content Management instance.

With all code and content changes up to date, you can deploy the front-end application to Netlify.

To deploy the application to Netlify:

Select the Git provider where your project source code is hosted, then choose your repository.
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.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.
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.
Click Add environment variables and enter the following variables:
- SITECORE_API_KEY - the Edge API key. Enter the token you generated previously.
- GRAPH_QL_ENDPOINT - https://edge.sitecorecloud.io/api/graphql/v1 . The GRAPH_QL_ENDPOINT is required for Sitecore Experience Edge. By default, the endpoint is calculated using the resolved Sitecore API hostname and the config.graphQLEndpointPath option defined in your package.json file.
- JSS_APP_NAME - the name of your site. For example, SitecoreAI Demo. It overrides the value set in the package.json file (config.appName), which does not always contain your site name.
- FETCH_WITH - either GraphQL or REST. This has to match the value in your solution’s .env file.
- PUBLIC_URL - Your Netlify-provided site URL (for example, https://<REPO/SITE>Name>.netlify.app>).
  
  Important
  
  Required if your application uses a JSS version earlier than 21.3.0.
- Any other custom environment variables you’ve added to your .env file. Netlify recommends that all environment variables are added to the Netlify site configuration.
- If your application includes the Next.js Personalize add-on, add the personalization-specific environment variables.
- If you are building a very large website, enable retries for requests to the SitecoreAI Experience Edge GraphQL endpoint.
Click Deploy site.
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 a SitecoreAI 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:

In the Build & Deploy section, in the Build settings, click Configure.
Find the Runtime setting and select Next.js.
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, you must obtain an authentication token.

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

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

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

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

To verify the request was completed successfully, check that you received a 201 Created response status code.
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.

If you have suggestions for improving this article, let us know!