Getting started

The SDK supports Next.js 15 and 16. Check yours with npx next --version. Releases before 15.5.24 on 15, or 16.3.3 on 16, have critical security advisories, so upgrade if you can: see Check your Next.js version. Next.js 14 is not supported, because it will not get fixes for them. These steps use the App Router; the Next.js guide covers the Pages Router.

npm i @usegraft/sdk-next @usegraft/db
npm i -D @usegraft/cli

npx @usegraft/cli@latest init

This scaffolds graft.config.ts, creates sample content in content/pages/home.mdx, and sets up the static index.

npx graft compile

This validates your markdown files against the schema and writes an embedded SQLite index to .graft/index.db. The index is derived state: your files in Git stay authoritative, and recompiling rebuilds it at any time.

The client is the object your pages read through. Create it once, in its own module, so every page shares it:

import { openStaticIndex } from "@usegraft/db";
import { createGraft } from "@usegraft/sdk-next";
import { collections } from "@/graft.config";

export const graft = createGraft({
  index: await openStaticIndex(".graft/index.db"),
  collections,
});

It lives outside app/ on purpose. A Next.js page file may only export the page and its route options, so a client exported from app/page.tsx fails the build's type check.

Replace app/page.tsx to read the sample page and render it:

import { MdxBody } from "@usegraft/sdk-next";
import { notFound } from "next/navigation";
import { graft } from "@/lib/graft";

export default async function Page() {
  const home = await graft.getContent("pages", "home");
  if (!home) notFound();

  return (
    <main>
      <h1>{home.data.title}</h1>
      <p>{home.data.tagline}</p>
      <MdxBody source={home.body} />
    </main>
  );
}

home.data is typed from your schema: hover title in your editor and you will see string. MdxBody renders the Markdown body on the server.

Start your dev server and open http://localhost:3000:

npm run dev

You should see the heading Hello, Graft, its tagline, and the body text from content/pages/home.mdx. Edit that file, run npx graft compile again, and refresh to see the change.

mkdir my-graft-site && cd my-graft-site
npm init -y
npm pkg set type=module
npm i @usegraft/db @usegraft/sdk-core
npm i -D @usegraft/cli tsx typescript @types/node
npx @usegraft/cli@latest init

type=module makes the project an ES module, so the script in the last step can use await at the top level.

npx graft compile

This compiles content/pages/home.mdx into .graft/index.db.

Create read.ts:

import { openStaticIndex } from "@usegraft/db";
import { createClient } from "@usegraft/sdk-core";
import { collections } from "./graft.config";

const index = await openStaticIndex(".graft/index.db");
const graft = createClient({ index, collections });

const home = await graft.getDocument("pages", "home");

console.log("Title:", home?.data.title);
console.log("Tagline:", home?.data.tagline);

Without a framework you use @usegraft/sdk-core directly, whose read method is getDocument. The framework packages wrap the same call and name it getContent. Both return the same typed document.

Run the script:

npx tsx read.ts

You will see the values from content/pages/home.mdx:

Title: Hello, Graft
Tagline: Content lives in git; the index is a file.

npm i @usegraft/sdk-astro @usegraft/db
npm i -D @usegraft/cli

npx @usegraft/cli@latest init

npx graft compile

In src/pages/index.astro:

---
import { openStaticIndex } from "@usegraft/db";
import { createGraft } from "@usegraft/sdk-astro";
import { collections } from "../../graft.config";

const graft = createGraft({
  index: await openStaticIndex(".graft/index.db"),
  collections,
});

const home = await graft.getContent("pages", "home");
---

<main>
  <h1>{home?.data.title}</h1>
  <p>{home?.data.tagline}</p>
</main>