Notion Reference Architecture

Overview

Production-grade architecture for Notion integrations using @notionhq/client. This skill defines a four-layer architecture — client singleton, repository pattern, service layer, and caching — that scales from simple scripts to enterprise applications. It covers multi-integration setups (reader + writer tokens), event-driven processing, headless CMS patterns, and comprehensive testing strategies.

Notion API version: 2022-06-28 | Rate limit: 3 requests/second per integration | Max page size: 100

Prerequisites

• Node.js 18+ with TypeScript strict mode enabled
• @notionhq/client v2.x installed (npm install @notionhq/client)
• A Notion internal integration created at https://www.notion.so/my-integrations
• NOTION_TOKEN environment variable set with the integration token
• Target databases/pages shared with the integration via "Add connections"

Instructions

Step 1: Establish the Client Singleton with Retry and Rate Limiting