Walkthrough: Deploying JSS Next.js apps to Netlify

Version: 22.x

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

This walkthrough describes how to:

  • Deploy a Next.js JSS app to Netlify.

  • Configure webhooks to redeploy the app automatically when published Sitecore data changes.

Note

This procedure assumes you already have a Next.js JSS app set up and connected to a Sitecore instance.

Deploy a Next.js JSS app to Netlify

To deploy your app to production:

  1. Commit and push your Next.js JSS application changes to your GitHub repository.

  2. In the browser, go to https://app.netlify.com/start. Log in to or sign up for a Netlify account.

  3. In Netlify, select the Git provider where your project is hosted, then choose your repository.

  4. In the Base directory field, enter the path to the root folder of the Next.js application.

  5. Click Add environment variables, and enter the following variables:

    • SITECORE_SITE_NAME  (for JSS 21.6.0 and later) or JSS_APP_NAME (for older JSS versions) - the name of your Sitecore site. It overrides the value set in the package.json file for the config.appName property, which does not always contain your site name.

    • SITECORE_API_KEY - your Sitecore API key. For Sitecore XM, the SITECORE_API_KEY is your Sitecore SSC API key or, if using Sitecore Edge Delivery, the Sitecore Experience Edge API key.

    • SITECORE_API_HOST - your Sitecore API hostname.

      Note

      The SITECORE_API_HOST is not required for Sitecore Experience Edge.

    • GRAPH_QL_ENDPOINT - your GraphQL endpoint. The GRAPH_QL_ENDPOINT is required for Sitecore Experience Edge. For Sitecore XM, this is typically optional. By default, the endpoint is calculated using the resolved Sitecore API hostname and the config.graphQLEndpointPath option defined in your package.json file.

    • FETCH_WITH - the data-fetching approach for your application. Set to 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://<SITE_NAME>.netlify.app>).

      Important

      This is 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 be added to the Netlify site configuration.

  6. Click Deploy site.

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

Configure webhooks to redeploy the app with updated content

You can use webhooks to trigger automatic redeployments of your JSS Next.js app. When using Sitecore Experience Edge for XM, you can configure webhooks that redeploy the JSS app when new data reaches the Edge Delivery Platform. Alternatively, you can enable Sitecore webhooks that trigger when the publishing process in your Sitecore instance finalizes.

Use Webhooks with Sitecore Experience Edge for XM

When using Experience Edge for XM, you can trigger static site generation, cache clearing, and other automated activities when your 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:

  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.sitecoreclo"d.io/"pi"admin/v1/webho"k w"th "he"following body:

    RequestResponse
    {
   "label": "My"new we"ho"k",
"  "ur"": "<yo"r-netlify"build-hook-ur">""
   "method": "POST",
   "headers":"{
     "Authorizatio"":""Bearer: <edge-a"thentication-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.

Enable the Sitecore XM publish:end webhook

Using the Sitecore XM publish:end webhook, you can automatically trigger static site generation, cache clearing, and other automated activities when the publishing process finalizes in Sitecore.

To enable the Publish:end hook:

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

  2. Create a webhook configuration based on the example /App_Config/Sitecore/JavaScriptServices/Sitecore.JavaScriptServices.AppServices.PublishingWebHook.config.example, and include it in your solution:

    • Set the required url option to the URL of the Netlify deploy hook.

    • Define the method option with a value of POST or GET. This optional configuration specifies the HTTP method for invoking the webhook.

    • Define the site for which to trigger the webhook when publishing finalizes. By default, Sitecore triggers the webhook for every published item. If you provide the site parameter, the webhook is invoked if the published item root is an ancestor, descendant, or equal to the configured site's root item.

  3. Deploy the webhook configuration to your Sitecore instance.

  4. Publish your items.

  5. On Netlify, check that the end of the publishing process triggered a new deployment.

Do you have some feedback for us?

If you have suggestions for improving this article,