Next.js Integration

Use NotCMS in Next.js server code so the secret key never reaches the browser. Start with the quickstart inside a Next.js App Router project. The examples below use NotCMS 0.5.0 or later and a blog database with a published checkbox. Replace names with those in your generated schema.

Use the generated client

notcms init creates the schema and exports nc. Next.js loads .env.local on the server, so import that client from your server component or server-only helper. Do not import it into a component marked "use client". If you create a client yourself, pass schema to new Client({ schema }); credentials alone cannot define the typed queries.

Fetch a public list

Call a helper like this from an async server component. Adjust the relative import to the location of your generated schema:

import { nc } from "./notcms/schema";

export async function getPublishedPosts() {
  const [posts, error] = await nc.query.blog.list({
    where: { published: true },
  });
  if (error) throw error;
  return posts;
}

export type BlogSummary = (typeof nc.query.blog.$inferPages)[number];

Render post.title and link to /blog/${post.id}. Properties you defined in Notion are under post.properties; the page title and ID are top-level fields. Throwing a query error allows a Next.js error boundary to handle service failures instead of displaying an empty successful list.

Fetch a detail page

A property lookup can apply the publication rule while retrieving the body:

import { nc } from "./notcms/schema";

export async function getPublishedPost(id: string) {
  const [post, error] = await nc.query.blog.getFirst({
    where: { id: { in: [id] }, published: true },
  });
  if (error) throw error;
  return post;
}

export type BlogPage = typeof nc.query.blog.$inferPage;

In app/blog/[id]/page.tsx, await params to read the ID, call this helper, and call Next.js notFound() only when the result is null. Service errors should remain errors. getFirst reads synchronized content, so a change in Notion becomes visible after the next sync. See single-page queries for the differences from get(id). The Markdown body is post.content, not post.properties.content. Render it with a Markdown renderer appropriate for your content’s trust level. If HTML is allowed, sanitize untrusted HTML before inserting it into the page.

Choose a publication and refresh policy

For scheduled dates, language fallback, and separate list/detail checks, use the tested content recipes. That guide includes Next.js route examples with asynchronous params. The reusable query and publication code lives in examples/content-recipes and is covered by SDK tests. After Notion synchronization, refresh any application cache you configured. A statically built deployment needs a rebuild to include edits or remove an unpublished page. Choose that behavior for your application explicitly; an SDK request does not invalidate Next.js caches or trigger deployments.

Getting Started

Usage

CLI Commands

Examples

Next.js Integration

Use the generated client

Fetch a public list

Fetch a detail page

Choose a publication and refresh policy

​Use the generated client

​Fetch a public list

​Fetch a detail page

​Choose a publication and refresh policy

Use the generated client

Fetch a public list

Fetch a detail page

Choose a publication and refresh policy