Install

A Backmatter host is a Next.js app. The content still lives in that app's repository.

Quick start

From the app root:

bunx backmatter init

That writes backmatter.config.ts, app/[[...backmatter]]/page.tsx, instrumentation.ts, and a .gitignore entry for the generated .backmatter/ folder.

Configure Next

Wrap the Next config:

import { withBackmatter } from "@backmatter/next/config";

export default withBackmatter({
  // your Next config
});

withBackmatter turns on Cache Components and regenerates .backmatter/ when you add or remove a model, block, or layout. It maps that folder to the backmatter import, and adds the same map to tsconfig.json, so every file uses one path:

import { cms } from "backmatter";

Read from the repo

Until you connect a workspace, cms reads content/ from disk. The files in the repo are the site. Set workspaceId in backmatter.config.ts when the site should load published content from Backmatter. Tokens stay in the environment: BACKMATTER_API_URL, BACKMATTER_CONTENT_TOKEN, BACKMATTER_PREVIEW_TOKEN, and BACKMATTER_HOST_TOKEN.

Next, add a first document: a model, a file, and a URL.