notion-local-dev-loop

name	notion-local-dev-loop
description	Configure Notion local development with a dedicated dev integration, test mocking, and hot reload. Use when setting up a Notion development environment, writing tests for Notion code, or establishing a fast iteration cycle against the Notion API without risking production data. Trigger with "notion dev setup", "notion local development", "mock notion", "notion test environment".
allowed-tools	Read, Write, Bash(npm:*), Bash(pnpm:*)
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

Notion Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Notion integrations. This skill creates a dedicated dev integration with its own token, structures the project for testability, mocks the Notion SDK in unit tests, and runs gated integration tests against a sandboxed dev workspace — so production data stays safe while you iterate quickly.

Prerequisites

• Completed notion-install-auth setup (you have a working Notion integration)
• Node.js 18+ with npm/pnpm, or Python 3.10+
• A Notion workspace where you can create test pages and databases

Authentication

This workflow uses a separate dev integration token, never the production token. The Notion SDK reads NOTION_TOKEN from the environment automatically. Store the dev token (prefix ntn_) in a git-ignored .env.development and commit a .env.example template so teammates know which variables to fill in. Token creation is covered by the notion-install-auth skill; Step 1 below wires it into the dev sandbox.

Instructions

Step 1: Create a Dev Integration and Workspace Sandbox

Create a separate integration exclusively for development so writes can never touch production data.

1. Go to Settings & Members > Connections > Develop or manage integrations (or visit developers.notion.com)
2. Click New integration and name it My App — Dev
3. Copy the token (starts with ntn_) into .env.development
4. Create a dedicated Dev Workspace page (or a top-level "Dev Testing" page) and share it with the dev integration
5. Inside that page, create test databases that mirror your production schema

# .env.development — git-ignored, dev only
NOTION_TOKEN=ntn_dev_xxxxxxxxxxxxxxxxxxxx
NOTION_TEST_DATABASE_ID=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
NOTION_TEST_PAGE_ID=ffffffff-0000-1111-2222-333333333333

# .env.example — commit this as a template
NOTION_TOKEN=ntn_your_dev_token_here
NOTION_TEST_DATABASE_ID=your_test_db_id
NOTION_TEST_PAGE_ID=your_test_page_id

Recommended project layout — a notion/ module the app imports, and split unit/integration tests:

my-notion-project/
├── src/
│   ├── notion/
│   │   ├── client.ts          # Singleton with retry + rate-limit awareness
│   │   ├── queries.ts         # Database query wrappers
│   │   └── helpers.ts         # Property extractors, rich text builders
│   └── index.ts
├── tests/
│   ├── unit/
│   │   └── notion.test.ts     # Mocked SDK tests
│   └── integration/
│       └── notion.test.ts     # Live API tests (gated)
├── .env.development            # Dev token (git-ignored)
├── .env.example                # Template for team
├── .gitignore
├── package.json
├── tsconfig.json
└── vitest.config.ts