makenotion/notion-cookbook

Purpose and Repository Shape

Notion Cookbook is a collection of independent, runnable TypeScript/Node.js recipes for the Notion API and Notion Workers. It is not one deployable application: each example, Worker, or agent skill is a separately configured project. The root discovery and operating surfaces are README.md, catalog.json, and AGENTS.md.

Recipe Catalog and Selection Boundary

catalog.json is the machine-readable directory of runnable projects and supported commands; it is the intended entry point for coding agents. AGENTS.md defines the workflow for locating, adapting, and validating a selected recipe. Root scripts operate across projects rather than providing a shared runtime: scripts/install-projects.sh, scripts/typecheck-projects.sh, and scripts/test-projects.sh.

Local Notion API Examples

Self-contained Node.js examples demonstrate direct use of the official Notion JavaScript SDK, with per-project dependencies, TypeScript configuration, environment variables, and README-driven commands. Entrypoints are generally project-local scripts such as examples/database-email-update/index.ts and examples/notion-github-sync/index.ts. The browser/server exception is the Express form app, split between examples/web-form-with-express/server.ts and static/UI assets under examples/web-form-with-express/public.

Notion Worker Runtime

Worker projects are server-side extensions intended for deployment with the Notion Workers CLI (ntn) and attachment to Notion Agent connections. Each Worker is independently packaged, with its execution entrypoint conventionally in src/index.ts, for example workers/airflow/src/index.ts, workers/duckdb-query/src/index.ts, and workers/chart-generator/src/index.ts. The Worker boundary separates Notion’s invocation/deployment contract from service-specific adapters and workflow logic.

Sync Workers: External Source to Managed Notion Data

Sync Workers ingest external provider data, map it into managed Notion databases, and often preserve incremental state. Provider clients and resource modules isolate remote APIs from synchronization orchestration: workers/github-sync/src/index.ts, workers/github-sync/src/github.ts, workers/github-sync/src/issues.ts; workers/linear-sync/src/index.ts, workers/linear-sync/src/linear.ts, workers/linear-sync/src/sync-state.ts; and workers/snowflake-sync/src/index.ts, workers/snowflake-sync/src/transform.ts, workers/snowflake-sync/src/schema.ts. Supported boundaries include GitHub, CRM/support/task systems, warehouse databases, and Notion.

Agent Tools and Query/Action Flows

Tool Workers expose repeatable agent-callable operations rather than persistent synchronization. Common structure is entrypoint → authentication/configuration → provider client → domain operation. Examples include read-only database querying in workers/postgres-query/src/index.ts, workers/postgres-query/src/postgres.ts, workers/postgres-query/src/sql.ts; cross-service incident workflows in workers/sentry-pagerduty-incident-tools/src/index.ts, workers/sentry-pagerduty-incident-tools/src/sentry.ts, workers/sentry-pagerduty-incident-tools/src/pagerduty.ts; and deployment actions in workers/vercel-production-deployment-tools/src/index.ts, workers/vercel-production-deployment-tools/src/release.ts.

Event and UI Extension Paths

The webhook pattern accepts external events, verifies/parses them, then writes/upserts Notion records: workers/zendesk-webhook/src/index.ts, workers/zendesk-webhook/src/webhook.ts, workers/zendesk-webhook/src/notion.ts. Custom Blocks are a distinct full-stack extension shape: Worker backend entrypoints under workers/custom-blocks/habit-tracker/src/index.ts support Vite/React block clients such as workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/App.tsx and Notion-backed client state in workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/notionStore.ts.

Agent Skills and Documentation Assets

skills/claude provides instruction-centric capabilities—knowledge capture, meeting intelligence, research documentation, and specification-to-implementation—rather than executable services. Each skill centers on a SKILL.md contract with references, examples, and evaluation fixtures, e.g. skills/claude/knowledge-capture/SKILL.md, skills/claude/meeting-intelligence/SKILL.md, and skills/claude/spec-to-implementation/SKILL.md. Shared user-facing guidance is kept in docs/ and project-local READMEs.