notion-sdk-patterns

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 <[e-mail]>
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', :  }],
});