Skip to main content
Custom blocks are in private alpha:
  • Do not discuss publicly or share with anyone outside your workspace.
  • Access must be enabled per workspace. Installing the SDK does not grant access.
  • These APIs may experience breaking changes without notice.

​
Custom blocks

Use these commands to preview custom blocks, prepare sample data, and insert deployed blocks into Notion. Custom blocks deploy with their worker through ntn workers deploy. See the custom blocks quickstart for the full workflow.

​
dev

Run a local dev shell for the custom blocks in a worker:
Run the command from the worker root, or supply the worker’s path:
The dev shell runs through the @notionhq/custom-blocks-dev-shell package. The CLI detects your worker’s package manager and starts the package with npx, pnpm dlx, or bunx. See previewing before deploy to connect sample data and configure property mappings.

​
sample

Save a data source’s schema and sample rows as a local JSON file for the dev shell:
The command accepts a data source ID, database ID, or Notion URL. By default, it saves up to 10 rows to data/<key>.json. The key comes from the data source’s name. Restart the dev shell after changing sample files. See previewing before deploy to connect the sample source to your block.

​
make

Insert a deployed custom block into a Notion page or block. Run this command from the deployed worker root:
If the block declares data sources, configure its bindings in Notion before it renders. See binding a block to Notion data.

​
Place custom blocks on pages

Use ntn pages create with a <custom-block definition-id="…" /> tag in the page content. See Place custom blocks with markdown for a complete example and App definition-key syntax. These are already documented in the CLI command reference and are the commands you use most when working on a custom block.