Integration · Framework

BetterCMS and Next.js

The Next.js adapter is @bettercms-ai/next, built for the App Router. It gives you a typed client, cache aware reads that flow through the Next data cache, tag based revalidation on publish, draft preview through next/headers, and a generated llms.txt route. It needs Next 14 or later and React 18 or later.

Package
@bettercms-ai/next
Requires
Next 14, React 18, App Router
Category
Framework

Set it up

Five steps. Step four is the one that decides whether an edit appears in a second or in a minute.

  1. 01 Install the adapter
  2. 02 Generate your types
  3. 03 Create the client
  4. 04 Read an entry, and tag it
  5. 05 Serve llms.txt

Forms render natively with BcmsForm from @bettercms-ai/next/form: real inputs, no iframe, your own styles. It handles conditional fields, query prefill, the honeypot, an optional Turnstile widget, validation and submission.

  1. 01

    Install the adapter

    Peers are next 14 or later and react 18 or later.

    terminal
    npm install @bettercms-ai/next
  2. 02

    Generate your types

    Codegen turns your content models into a BetterCMSSchema registry, which is what makes getEntry and listEntries autocomplete by model slug.

    Commit the generated file and rerun it after a schema change. The BetterCMS GitHub Action does this on every build.

    terminal
    BETTERCMS_API_KEY=bcms_xxx npx @bettercms-ai/codegen \
      --out src/bettercms.generated.ts
  3. 03

    Create the client

    One client for the app. The revalidate value is the default ISR window in seconds; false means always fresh.

    lib/cms.ts
    import { createBetterCMS } from "@bettercms-ai/next";
    import type { BetterCMSSchema } from "./bettercms.generated";
    
    export const cms = createBetterCMS<BetterCMSSchema>({
      workspace: "acme",
      apiKey: process.env.BETTERCMS_API_KEY,
      revalidate: 60,
    });
  4. 04

    Read an entry, and tag it

    Reads go through fetch, which Next patches into its data cache. Pass a tag and call revalidateTag on publish and the page updates without a rebuild.

    getEntry returns null on a 404. listEntries throws BetterCMSError for an unknown workspace or model, and returns an empty page for an empty one.

    app/blog/[slug]/page.tsx
    import { cms } from "@/lib/cms";
    import { notFound } from "next/navigation";
    
    export default async function Post({ params }) {
      const { slug } = await params;
      const entry = await cms.getEntry(slug, {
        revalidate: 300,
        tags: [`post:${slug}`],
      });
      if (!entry) notFound();
      return <article><h1>{entry.fields.title}</h1></article>;
    }
  5. 05

    Serve llms.txt

    One route handler produces the answer engine index from your models. generateLlmsTxt and fetchModels are exported too if you want to build it yourself.

    Author controlled values are escaped, so content cannot forge the document structure.

    app/llms.txt/route.ts
    import { llmsTxtRoute } from "@bettercms-ai/next";
    
    export const GET = llmsTxtRoute({
      models,
      title: "Acme",
      workspace: "acme",
    });

What it does not do

  • A section page needs its components

    Pages authored as sections are lists of component blocks, and a component block whose definition was not delivered renders nothing. Pass components from readComponents() into BcmsBlocks alongside forms from readForms(). Skip it and the page builds green and shows only your nav and footer.

  • App Router only

    The adapter is written for the App Router. There is no documented Pages Router path, so a Pages Router app reads the Delivery API through @bettercms-ai/sdk instead and does its own caching.

  • Revalidation is yours to wire

    Tags do nothing on their own. Something has to call revalidateTag when content publishes, which means a route handler on your side and a webhook on the BetterCMS side. The adapter gives you the tags, not the trigger.

  • It does not host the site

    This is the headless path. BetterCMS holds the content and you deploy the Next.js app wherever you like. BetterCMS Cloud, where BetterCMS renders and hosts the pages, is a different setup.

Questions people ask

  • Yes. @bettercms-ai/next is a first party App Router adapter with typed reads, cache aware fetching, tag based revalidation, draft preview and an llms.txt route. It needs Next 14 or later and React 18 or later.

  • Tag the read, then invalidate the tag. Pass tags to getEntry or listEntries, add a route handler that calls revalidateTag, and point the project revalidation webhook at it in Project settings. The alternative is a full rebuild through a deploy hook, which is simpler and slower. Tag invalidation updates one page; a deploy hook rebuilds the site.

  • Not through this adapter. It is written for the App Router and its cache behavior depends on the App Router data cache. A Pages Router app can still read content: @bettercms-ai/sdk is a plain typed client for the Delivery API and works anywhere JavaScript runs.

  • Yes. BcmsForm ships from @bettercms-ai/next/form as its own client entry and renders real inputs rather than an iframe. It handles conditional fields, URL query prefill, the honeypot, an optional Turnstile widget, validation errors and submission, and it needs no API key because the endpoint is Turnstile gated. Outside React, submitForm from @bettercms-ai/sdk does the same job from anywhere.

Your next website starts here

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