Quick Start

This guide uses NotCMS 0.5.0 or later. You need Node.js 18.17 or later and a project that can run TypeScript on the server. Contributor tooling has separate Node requirements; those do not change the SDK’s supported runtime.

1. Connect a database

In the dashboard, create or select a workspace, connect Notion, and grant access to the database you want to use. Register the database and wait for its initial synchronization to complete. A database that has not synchronized cannot provide the content and schema needed below.

2. Install and initialize

Run these commands in your application’s root:

npm install notcms
npx notcms init

pnpm add notcms
pnpm exec notcms init

yarn add notcms
yarn notcms init

bun add notcms
bunx notcms init

init creates notcms.config.json, offers browser login when credentials are missing, and pulls the first schema. Select the workspace containing your registered database. By default, credentials go into .env.local and the schema goes into src/notcms/schema.ts. The command prints a query using your actual database name. See init for custom paths. Keep .env.local out of Git. The CLI reads it, but your application must also load it in its server runtime. Next.js loads .env.local; a plain Node.js app can use dotenv.config({ path: ".env.local" }) before importing the generated client. Never expose NOTCMS_SECRET_KEY through browser environment variables. See client initialization.

3. Fetch a list

Run the query on the server. Replace blog and the property names with those from your generated schema. This example assumes a published checkbox:

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

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

for (const post of posts) {
  console.log(post.id, post.title);
}

The import above fits src/example.ts with the default schema path. The SDK returns an error tuple; check error before reading the data. An empty array means the query succeeded but no synchronized pages matched your rule.

4. Fetch Markdown content

Copy a page ID from the list to retrieve its body:

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

const [post, error] = await nc.query.blog.get("your-page-id");
if (error) throw error;
console.log(post.content);

get looks up an ID without applying the list’s publication filter. Before rendering a public detail page, check its publication rule again. Use the tested content recipes for that workflow. If your URL uses a slug, see getFirst.

Keep the site current

After editing Notion content, wait for synchronization and refresh the site’s cache or rebuild it as appropriate. After changing database properties, also run npx notcms pull and your application’s typecheck. pull retrieves the synchronized schema; it does not start a content sync. Continue with Next.js, Astro, or schema checks in CI. For older installations, see migration.

Getting Started

Usage

CLI Commands

Examples

1. Connect a database

2. Install and initialize

3. Fetch a list

4. Fetch Markdown content

Keep the site current

​1. Connect a database

​2. Install and initialize

​3. Fetch a list

​4. Fetch Markdown content

​Keep the site current

1. Connect a database

2. Install and initialize

3. Fetch a list

4. Fetch Markdown content

Keep the site current