How to Integrate Cloudflare Pages with Your Headless CMS

What is Cloudflare Pages?

Cloudflare Pages is Cloudflare's platform for deploying frontend applications and static sites to its global network. Teams use it with frameworks like Astro, Next.js, Nuxt, Remix, Gatsby, SvelteKit, and Vue, with builds connected to Git and optional server-side logic through Pages Functions. It's a common choice when you want fast deploys, edge delivery, branch previews, and built-in Cloudflare services in the same workflow.

Why integrate Cloudflare Pages with a headless CMS?

Cloudflare Pages can ship a new build every time code changes, but content changes are a different problem. If an editor publishes a pricing page at 2:00 PM, you don't want someone to manually click “Retry deployment,” commit a JSON file, or wait for a nightly batch job. Connecting Cloudflare Pages to a headless CMS category tool solves that gap by turning publish events into deploy events.

Architecture overview

A typical setup starts in Sanity Studio, where editors publish structured documents such as pages, posts, products, or navigation items. That content is held as typed JSON in the Content Lake. When a publish event happens, a Sanity webhook or Function runs with a filter such as _type in ["page", "post"] && !(_id in path("drafts.**")). The handler uses GROQ to fetch the exact fields Cloudflare Pages needs, including referenced data like author names, category slugs, or navigation labels. Then it calls Cloudflare Pages through a deploy hook URL or the Cloudflare Pages API, usually POST /client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments for a Git-connected project. Cloudflare Pages starts a new build, your framework fetches fresh content from Sanity during npm run build, the output is deployed to Cloudflare's edge network, and visitors receive the updated page from the nearest Cloudflare location. If you need server-side processing before the deploy, use Sanity Functions to run the logic on content events without running a separate webhook server.

Common use cases

Step-by-step integration

1. 1

   Create the Cloudflare Pages project

   In Cloudflare, create a Pages project from GitHub or GitLab, choose your framework preset, set the build command such as npm run build, and set the output directory such as dist, build, or .output/public. Add environment variables for SANITY_PROJECT_ID, SANITY_DATASET, and SANITY_API_VERSION. If you'll trigger deploys through the API, create a Cloudflare API token with Account, Cloudflare Pages, Edit permission. If you prefer the simpler path, create a Pages deploy hook under Settings, Builds & deployments, Deploy hooks.

2. 2

   Install the SDKs your integration needs

   In your webhook service, Sanity Function, or build tooling, install the Sanity client and Cloudflare SDK with npm i @sanity/client cloudflare. In the Cloudflare Pages frontend app, use @sanity/client to fetch content during build time, or fetch from your own API route if you need extra permission checks.

3. 3

   Model the content in Sanity Studio

   Define schemas for the content Cloudflare Pages will render. A page schema usually needs title, slug, seoTitle, seoDescription, body, publishedAt, and references such as author or parentPage. Keep route-critical fields typed and required, especially slug.current, so your build can generate stable paths.

4. 4

   Create the publish trigger

   Create a Sanity webhook or Function that runs only for published content. Use a filter like _type in ["page", "post", "product"] && !(_id in path("drafts.**")). Include the document _id, _type, and slug in the projection so the handler can decide whether to trigger a production deploy, preview deploy, or no deploy.

5. 5

   Call Cloudflare Pages

   For a Git-connected Pages project, call the Cloudflare Pages deployment API or POST to the deploy hook URL. The deploy hook is easier to maintain because Cloudflare owns the secret URL. The API token path gives you more control if you need to inspect projects, choose branches, or build internal tooling around deployments.

6. 6

   Test the frontend build

   Publish a test document in Sanity Studio, confirm the webhook fires, confirm Cloudflare Pages starts a deployment, and inspect the build logs. Then verify that your frontend GROQ query returns the expected fields and that missing optional fields don't break the build.

Code example

import Cloudflare from "cloudflare";
import {createClient} from "@sanity/client";

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: "2025-02-19",
  useCdn: false,
  token: process.env.SANITY_READ_TOKEN
});

const cloudflare = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN!
});

export async function POST(req: Request) {
  const event = await req.json();

  const page = await sanity.fetch(
    `*[_id == $id][0]{_id, _type, "slug": slug.current, title}`,
    {id: event._id}
  );

  if (!page?.slug) {
    return Response.json({skipped: true, reason: "No routable slug"});
  }

  const deployment = await cloudflare.pages.projects.deployments.create(
    process.env.CLOUDFLARE_PAGES_PROJECT!,
    {
      account_id: process.env.CLOUDFLARE_ACCOUNT_ID!,
      branch: "main"
    }
  );

  return Response.json({
    triggered: true,
    slug: page.slug,
    deploymentId: deployment.id
  });
}

How Sanity + Cloudflare Pages works

CMS approaches to Cloudflare Pages

Keep building

Explore related integrations to complete your content stack.