Install the client
TypeScript declarations ship with the package. There is no separate types package to add.
npm install @bettercms-ai/sdk Every published page and entry is readable over the BetterCMS Delivery API, and @bettercms-ai/sdk is the typed client for it. Create a client against a workspace, then read one page with getContent, a page of results with listContent, or every result with listContentAll, which follows pagination for you. It is plain TypeScript with no framework attached, so it runs in a build script, a worker or a framework nobody has written an adapter for.
Four steps, and the fourth is the one that stops a rate limit becoming an outage.
Images have their own builder. @bettercms-ai/image-url assembles URLs against the media transform endpoint with width, height, format, quality, fit and dpr, and every method returns a new builder so a chain is safe to fork.
TypeScript declarations ship with the package. There is no separate types package to add.
npm install @bettercms-ai/sdk A workspace is the only required option. An API key is optional for published content and required for anything scoped.
import { BetterCMS } from "@bettercms-ai/sdk";
export const client = BetterCMS.site({
workspace: "my-workspace",
apiKey: process.env.BETTERCMS_API_KEY,
}); getContent takes a slug. listContent is paginated and returns items with hasNextPage and totalPages. listContentAll is an async iterator that follows pagination, with an all method when you want a capped array instead.
const page = await client.getContent("home");
const result = await client.listContent({ page: 1, perPage: 20 });
for await (const item of client.listContentAll()) {
console.log(item.entry.title);
}
const top = await client.listContentAll().all({ limit: 500 }); Failures throw BetterCMSError with a semantic code, so a 404 and a rate limit are different branches rather than the same string match.
CONTENT_NOT_FOUND, UNAUTHORIZED, FORBIDDEN, RATE_LIMITED, INTERNAL_ERROR and NETWORK_ERROR are the ones to handle.
import { BetterCMSError, ErrorCodes } from "@bettercms-ai/sdk";
try {
await client.getContent("does-not-exist");
} catch (err) {
if (err instanceof BetterCMSError) {
if (err.code === ErrorCodes.RATE_LIMITED) backOff();
if (err.code === ErrorCodes.CONTENT_NOT_FOUND) return null;
}
throw err;
} The Delivery API is REST. If a GraphQL layer is a requirement, that is a real gap and it is better known now than after a proof of concept.
This client reads published content. Writing goes through the Management API, which is what the dashboard and the MCP server use, and it takes a content:manage key.
The SDK is a thin typed client. The Next.js adapter adds cache aware reads because Next patches fetch; the plain SDK leaves caching to you.
A burst of reads can return RATE_LIMITED. Handle that code with a back off rather than a retry loop, especially in a build script that walks every entry.
No. The BetterCMS Delivery API is REST, and @bettercms-ai/sdk is the typed client for it. If your architecture requires GraphQL, that is a genuine gap rather than something to work around, and it is worth raising before a proof of concept rather than during one.
Yes. That is what the SDK is for. It is plain TypeScript with no framework dependency, so Nuxt, SvelteKit, Remix, a build script or a worker all read content the same way. What you lose without an adapter is the framework specific work: cache integration, draft preview wiring and ready made block components.
The client takes a workspace and an optional API key. Published content is readable with the workspace alone; anything scoped, including drafts, needs a key with the right scope. Keep server keys on the server. Both framework adapters keep them out of the client bundle for exactly this reason.
Generates an interface per content model plus a schema registry, so your types cannot drift from your models.
First party adapter: a bettercms() integration, typed loaders, draft preview, and components that render page blocks.
First party App Router adapter: typed cache aware reads, tag revalidation, draft mode, and a generated llms.txt route.
See BetterCMS running on your pages, not on a sample site.