Integration · Developer tool

TypeScript codegen

Codegen turns your BetterCMS content models into TypeScript. Your models are defined once, either in the dashboard schema builder or by an assistant through the MCP tools, and both write the same underlying field schema, so the generated types cannot drift from what your editors and agents actually create. This is the deterministic floor under the AI integration: if an agent mis-wires something, the committed types still say what the shape is.

Package
@bettercms-ai/codegen
Needs
A content:manage key
Category
Developer tools

Set it up

One command, then a decision about where it runs.

  1. 01 Run it in the site repository
  2. 02 Commit the generated file
  3. 03 Rerun it after a schema change
  4. 04 Optional: emit Live Preview bindings

Field types map predictably: text, date and datetime become string; richtext becomes RichText; image becomes BetterCMSImage; select becomes a union; a group becomes a nested object and a repeater becomes an array of one.

  1. 01

    Run it in the site repository

    The key comes from the dashboard under Settings, then API Keys, with the content:manage scope.

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

    Commit the generated file

    The output is source. Committing it means a fresh clone type checks without a network call, and a schema change shows up as a reviewable diff rather than as a surprise at build time.

  3. 03

    Rerun it after a schema change

    A CI step does this, and the BetterCMS GitHub Action does it on every build. Either way the committed types track the models.

    The generated BetterCMSSchema registry is what lets the Next.js adapter type getEntry by model slug.

  4. 04

    Optional: emit Live Preview bindings

    Pass a second output path and codegen also emits a schema derived binding helper. Spread a binding onto the element that renders a field, and the resulting data attribute is what makes the running site editable in place.

    terminal
    npx @bettercms-ai/codegen \
      --out src/bettercms.generated.ts \
      --bindings-out src/bettercms.bindings.generated.ts

What it does not do

  • References come back as ids

    A reference field generates a string and a multi reference generates an array of strings. Hydrating them is a read time concern, which the Next.js adapter handles with its depth option.

  • It does not watch

    There is no watch mode. Codegen runs when you run it, or when CI runs it. A schema change made while the dev server is up does not update the types on its own.

  • It reads the schema, not the content

    The output describes field shapes. It cannot tell you that a required field is empty on forty entries, because it never looks at an entry.

  • It needs a manage scoped key

    Reading the schema needs content:manage, which is more privilege than a delivery key. Keep it in CI secrets rather than in a developer shell profile.

Questions people ask

  • Run npx @bettercms-ai/codegen with a content:manage key and an output path. It reads the content models and writes an interface per model plus a BetterCMSSchema registry that maps model slugs to their field types. Commit the output and rerun after a schema change.

  • Yes, once you rerun codegen. The schema builder and the MCP tools write the same underlying field schema, so there is one source and the generated types describe it either way. That is the point of running codegen in CI: it is the deterministic floor under the agent.

  • Live Preview. The bindings file is a small schema derived helper you spread onto the element that renders each field, which stamps a data attribute the editor reads to make the running site editable in place. It is off by default and turns on with the bindings output flag.

Your next website starts here

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