Walkthrough: Deploying JSS Next.js apps to Vercel

Abstract

Deploy a JSS Next.js app to Vercel and configure webhooks for automatic redeployments

Vercel is an all-in-one platform with Global CDNs supporting the deployment and delivery of static and Jamstack apps. Vercel has first-class support for Next.js.

Your JSS Next.js application must be connected to a Sitecore instance.

This walkthrough demonstrates deploying the Next.js sample app generated by the jss create command to Vercel and configuring the necessary webhooks so that the application redeploys automatically when Sitecore data changes on the CD instance.

This walkthrough describes how to:

  • Deploy a Next.js JSS app to Vercel.

  • Configure webhooks to redeploy the app with updated content.

Deploy a Next.js JSS app to Vercel

Before deploying the Next.js JSS app, watch the following video to see the deployment process:

You must have a Next.js JSS app set up and connected to a Sitecore instance before you can continue.

To deploy your app to production:

  1. Perform the steps provided in the Next.js guide for Getting Started with deployment.

  2. Add environment variables to Vercel or modify .env file in the root folder of your JSS Next.js app.

    Note

    We recommend setting the environment variables in Vercel.

    • PUBLIC_URL - your Vercel deployment URL.

    • 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.

    • JSS_EDITING_SECRET - your secret token. The JSS_EDITING_SECRET is optional for deployments but necessary if you want to use a Sitecore editor with your JSS Next.js app deployed on Vercel.

    • 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.

  3. Push the changes to your Git provider.

Configure webhooks to redeploy the app with updated content

You can use webhooks to trigger automatic redeployments of your JSS Next.js app when the publishing process in your Sitecore instance finalizes or when new data reaches the Edge Delivery Platform.

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 deploy hook in Vercel and copy the URL of the webhook.

  2. Create 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 Vercel deploy hook.

    • Define the method option with a value of POST or GET . This configuration is optional. It configured the HTTP method for invoking 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 Vercel, check that the end of the publishing process triggered a new deployment.

Use Webhooks with Sitecore Experience Edge for XM

If you are using Sitecore Experience Edge, instead of triggering a webhook when the publishing process finalizes in Sitecore you can trigger webhooks when your data reaches the Edge Delivery Platform.

You can 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 Vercel when your data reaches the Edge Delivery Platform:

  1. Create a deploy hook in Vercel and copy the URL of the webhook.

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

    {
        "label": "My new webhook",
        "createdBy": "SOME_USER_ID",
        "uri": "YOUR_VERCEL_WEBHOOK_URL",
        "method": "GET"
    }
    
  3. To verify the request completed successfully, check that you received a 201 Created response status code.

  4. Make some changes in Sitecore and publish them.

  5. When the Experience Edge finishes processing the new data, the publishing process is complete and Vercel starts a new deployment.