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.
Use the local dev shell to preview your custom block before you deploy. It simulates Notion on your machine, so you can build a block and watch it change.

​
Run the local dev shell

Run it from the worker root, or pass a path. It reads the worker’s block declarations, so it picks up every block in the project at once. See the command reference for flags and setup.

​
Configure sample data

The dev shell reads sample sources from data/*.json at the worker root when it starts. Each file defines one source. Restart the dev shell after changing these files. For the quickstart’s issues declaration, create data/issues.json:
After you start the dev shell:
  1. Select your custom block.
  2. Connect each declared data source to a sample source.
  3. Check the property mappings. Map title to Title and status to Status for this example.
  4. Save the bindings to render the block.
Matching property names can help with mapping. A sample file does not automatically connect the block to that source.

​
What is real and what is not

Your block gets the same context a real Notion page provides: a block ID, a parent and page, a current user, user settings. Data sources are the interesting part. In Notion, a block does not render until every data source it declares is bound to a real one. In the dev shell, you connect them to sample sources and map their properties before the block renders. Those rows are not your workspace’s rows, so treat the dev shell as an approximation. Anything permissions-sensitive needs a second look once the block is bound to real data.

​
If a block will not load

Press \ inside a running block to log the messages passing between it and the host. It is the fastest way to see why a block is stuck loading. This is built into NotionCustomBlock, so it is only available to blocks using the React SDK.

​
Ship it

When everything looks right, run ntn workers deploy to deploy your changes to live block instances.