Integration · Hosting

BetterCMS and Vercel

BetterCMS does not deploy to Vercel for you. It calls a URL when content publishes, and you decide what that URL does. A Vercel deploy hook rebuilds the whole site; a route handler that calls revalidateTag updates one page in about a second. Both are two minutes of setup and the second one is what most teams want.

What connects
Publish webhook to a Vercel hook
Best with
@bettercms-ai/next tag revalidation
Category
Hosting

Set it up

Pick one of the two paths in step two. Everything else is the same either way.

  1. 01 Put the API key in the project
  2. 02 Choose a rebuild or a revalidate
  3. 03 Point BetterCMS at it
  4. 04 Tag your reads

Astro sites use the same webhook and point it at a deploy hook, because there is no equivalent of revalidateTag outside the Next.js data cache.

  1. 01

    Put the API key in the project

    Add BETTERCMS_API_KEY to your Vercel project environment variables, for every environment the site reads content in.

    Use a content:read key for production. Preview deployments that show drafts need content:read:draft instead.

  2. 02

    Choose a rebuild or a revalidate

    A deploy hook rebuilds the whole site. Create one in the Vercel project under Settings, then Git, then Deploy Hooks, and copy the URL.

    Tag revalidation updates one page. Add a route handler that calls revalidateTag and copy its URL instead. On a large site this is the difference between a minute and a second.

    app/api/revalidate/route.ts
    import { revalidateTag } from "next/cache";
    
    export async function POST(request: Request) {
      const { tag, secret } = await request.json();
      if (secret !== process.env.REVALIDATE_SECRET) {
        return new Response("Unauthorized", { status: 401 });
      }
      revalidateTag(tag);
      return Response.json({ revalidated: true });
    }
  3. 03

    Point BetterCMS at it

    Open the project in BetterCMS, go to Settings, and set the revalidation webhook to the URL you copied.

    That is the whole connection. BetterCMS calls it on publish and Vercel does the rest.

  4. 04

    Tag your reads

    A revalidate route only helps if the reads carry tags. Pass a tag to every getEntry and listEntries call you want to refresh individually.

    app/blog/[slug]/page.tsx
    const entry = await cms.getEntry(slug, { tags: [`post:${slug}`] });

What it does not do

  • There is no Vercel Marketplace app

    You will not find BetterCMS in the Vercel integrations directory. Everything on this page is a webhook you paste and an environment variable you set.

  • No environment variable sync

    Rotating a BetterCMS API key does not update it in Vercel. That is two places, by hand, and worth a calendar reminder.

  • Preview deployments need their own key

    A preview deployment that should show drafts needs a content:read:draft key and its own draft secret in the preview environment. Production keys will not return drafts, by design.

  • BetterCMS does not read your deployments

    The connection is one way. BetterCMS calls the hook and does not know whether the build succeeded, so a failed deploy shows up in Vercel and not in the CMS.

Questions people ask

  • Deploy the frontend to Vercel the way you normally would, then give it a BETTERCMS_API_KEY environment variable so it can read content. BetterCMS is the content source, not the deploy pipeline. To make a publish show up, set the project revalidation webhook in BetterCMS to either a Vercel deploy hook or your own revalidate route.

  • With a deploy hook, as fast as your build. With a route handler that calls revalidateTag, about a second, because only the tagged pages are invalidated. With neither, an edit appears when the cached read next expires.

  • No. There is no Vercel Marketplace listing. The connection is a webhook URL and an environment variable, which is two minutes of setup and nothing to install.

Your next website starts here

See BetterCMS running on your pages, not on a sample site.