| name | notion-sdk-patterns |
| description | Apply production-ready @notionhq/client SDK patterns for TypeScript and Python.
Use when implementing Notion integrations, building database queries with filters
and sorts, handling pagination, constructing rich text blocks, or establishing
team coding standards for Notion API usage.
Trigger with "notion SDK patterns", "notion best practices", "notion code patterns",
"idiomatic notion", "notion typescript", "notion python SDK".
|
| allowed-tools | Read, Write, Edit, Grep |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion","sdk","typescript","python"] |
| compatibility | Designed for Claude Code |
Notion SDK Patterns
Overview
Production-ready patterns for the official Notion SDK (@notionhq/client for TypeScript, notion-client for Python) covering client initialization, database queries with filters and sorts, cursor-based pagination, rich text construction, block manipulation, and type-safe error handling using SDK error codes.
The full workflow lives in three steps below. Each step shows the essential skeleton inline; deep variants (compound filters, generic pagination helpers, block manipulation, exhaustive error switches) are in references/patterns.md, and copy-paste task recipes are in references/examples.md.
Prerequisites
- Node.js 18+ with
@notionhq/client v2.x installed, or Python 3.9+ with notion-client
- A Notion integration token (
NOTION_TOKEN) from notion.so/my-integrations
- Target databases/pages shared with the integration (Share > Invite > select your integration)
- TypeScript 5+ with strict mode enabled (for TypeScript patterns)
Instructions
Step 1 — Initialize the Client and Query Databases
Set up the SDK client and execute a filtered, sorted database query.
TypeScript:
import { Client } from '@notionhq/client';
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const response = await notion.databases.query({
database_id,
filter: {
property: 'Status',
select: { equals: 'Active' },
},
sorts: [{ property: 'Created', : }],
});
