Notion custom blocks dev shell

A local dev shell for Notion custom block workers. It builds your worker, reads the manifest declared by your worker.customBlock(...) calls, serves each block with your project's own Vite, and renders them in a mock Notion host with sample data sources you can bind against.

Usage

From anywhere inside your worker project, with the Notion CLI (v0.20.0+):

ntn customblocks dev

Then open http://localhost:9873.

Options:

• [path] — point at a worker directory explicitly instead of detecting one from the current directory.
• --port <port> — serve the shell UI somewhere other than 9873.
• --block-base-port <port> — first port handed to the per-block dev servers (default 9876; blocks count up from there).

Reference

One page per topic, shipped in this package's docs/ so they're readable from node_modules:

• docs/bindings.md — connecting blocks to data sources: auto-mapping and compatibility rules, initialization, and live rebinding.
• docs/data-sources.md — local data sources: the src/data/*.json file format, value shapes per property type, validation, and how missing sources are materialized from the worker's declared schemas.

Requirements

• Node.js >= 20.19 for the shell itself. Use Node.js >= 22 for the standard Notion worker projects.
• The worker's dependencies installed (use its declared package manager; the standard projects use pnpm install), including vite and a build script that emits dist/index.js.