@notionhq/custom-blocks-dev-shell
v0.3.1
Published
Local development shell for Notion custom block workers.
Maintainers
Keywords
Readme
Custom blocks dev shell
The dev shell runs custom blocks in a local mock Notion host. It builds your worker and runs its
blocks with local sample data. Use it before ntn workers deploy.
Usage
Run this command from your worker project:
ntn workers customblocks devOpen the shell URL printed by the command. Blocks hot reload when their source files change. Each
run uses one port for the shell and all blocks. The default is 9873. If that port is occupied, the
launcher selects the next available port. You can start multiple runs without choosing a port for
each run. Stopping one run leaves the others active.
The shell and blocks keep separate browser origins through localhost subdomains:
http://localhost:9873: shellhttp://chart.localhost:9873: chart blockhttp://table.localhost:9873: table block
Block capability keys, such as "chart" in worker.customBlock("chart"), become lowercase hostname
labels. Unsupported characters become hyphens. The launcher shortens long labels and adds numeric
suffixes when keys conflict.
Chrome and Firefox resolve these localhost subdomains without setup. Older macOS Safari versions may need hostname setup. macOS 26 Tahoe fixed this resolution (WebKit issue). The launcher does not change hostnames on your system or install certificates.
Install @notionhq/custom-blocks-dev-shell in the worker's devDependencies to pin its version.
This also makes the reference docs available in node_modules. If you do not install it, the CLI
fetches the latest version each time.
Startup details for automation
Use --json to read startup details from stdout:
ntn workers customblocks dev -- --json
npx @notionhq/custom-blocks-dev-shell --jsonAfter the shell and block servers start, the launcher emits one JSON line. Logs and errors go to stderr. Example output, formatted for readability:
{
"event": "ready",
"shellUrl": "http://localhost:9875",
"workerDir": "/absolute/path/to/worker",
"devShellVersion": "0.1.115",
"customBlocks": [
{
"key": "task-board",
"url": "http://task-board.localhost:9875/",
"manifest": {
"version": 1,
"dataSources": {}
},
"sampleFilesByDataSource": {}
}
]
}URLs use the selected port and remain valid for the run. workerDir is absolute, and
devShellVersion identifies the running package version. Each block includes its capability key,
declared manifest, and selected sample files.
sampleFilesByDataSource includes automatic selections and --bind overrides, with paths relative
to workerDir. Slots without a selected file are omitted. The record is a startup snapshot, not a
description of current browser property mappings. Later edits do not emit another record.
Read the record without waiting for process exit. ready confirms that the shell and every block
URL returned HTTP 2xx. It does not confirm block rendering, data access, or complete bindings. The
checks allow 10 seconds after server setup. On timeout, stderr names the URLs that did not respond
successfully, and the process exits nonzero without a ready record.
Options
ntn workers customblocks dev -- \
--bind task-board.tasks=sample_tasks.json \
--bind-property task-board.tasks.title=task_nameThe -- separator is required to forward options through ntn. Omit it when running
custom-blocks-dev-shell directly.
[path]: Select a worker directory instead of using the current directory.--json: Write startup details as one JSON line. See startup details for automation.--port <port>: Require this port for the whole run. If occupied, the command fails with an explanation. Omit this option to enable automatic fallback.--bind <capabilityKey>.<dataSourceKey>=<sampleDataFileName>: Choose sample data. Repeat for multiple slots.--bind-property <capabilityKey>.<dataSourceKey>.<propertyKey>=<sourcePropertyKey>: Map a block property to a sample schema property. Repeat for multiple properties. Explicit mappings override automatic matches.
See bindings for source selection and property mapping rules.
Browser restrictions
The block iframe uses the same sandbox attributes as production: allow-scripts allow-same-origin,
with allow="clipboard-write". Forms, popups, top-level navigation, downloads, and modal dialogs
are blocked.
The shell and each block use separate origins, so a block cannot access the shell's DOM or storage.
Instances of the same block share localStorage. sessionStorage is also scoped to the browser
tab.
Block responses enforce a production-like content security policy (CSP) and send a
Connection-Allowlist header:
- Blocked features: Native form submission, browser workers,
<object>,<embed>, web app manifests, and<base>. - Scripts and styles: Bundled scripts and inline scripts/styles work. Runtime CDN scripts are blocked.
- Media and fonts: Notion-hosted media and Google Fonts use the same exceptions as production.
- External access: Network requests and nested frames may use any origin for now. Browser CORS checks still apply.
Differences from production
Native icon colors: The reference host accepts any string color and defaults omitted colors to gray. It does not emulate Notion's supported-color checks. A successful local write does not establish that Notion supports the color.
Local origins: Blocks and the shell use HTTP localhost origins instead of production HTTPS origins.
Hot reload: CSP permits the block's exact WebSocket host and port for Vite HMR.
External access: Production uses workspace-approved external origins. The dev shell currently allows all origins. Configurable limits will be added later.
Embedding hosts: Any host may embed local blocks for now, including Notion apps in every environment. Configurable limits will be added later.
Parent navigation policy: The shell does not apply production's parent navigation CSP. The block's CSP alone cannot prevent it from navigating its own iframe to another document.
Sample data: SDK handlers use local sample data instead of production permissions and persistence.
Developer control: Vite plugins are developer-controlled, so the dev shell is not a security boundary for untrusted code.
Reload behavior
| Change | What happens | | ------------------------------------------------------ | ---------------------------------------------------------------------- | | Block code or styles | Vite applies hot updates. | | Sample data selected by the active block | The block restarts and clears its UI state and in-memory data changes. | | Worker declarations, including data source definitions | Restart the dev shell to rebuild the manifest. |
The header shows when sample data was last updated. Select a data source in the sidebar to view and copy its file path. See live updates and local writes for error recovery.
Error surface
The viewport shows an error when a block cannot initialize or an uncaught runtime error prevents rendering. For host and runtime errors, use Copy to copy the details or Retry to create a new host and iframe.
A missing or invalid worker manifest shows an error before the block starts. Fix the block declaration and restart the dev shell to rebuild the manifest.
An unexpected iframe reload stops the host and shows a retryable iframe_reloaded error. The host
ignores later connections. The dev shell does not replace the iframe automatically. Use Retry to
create a new host and iframe.
External navigation
links.open uses a host-owned confirmation before opening the exact normalized URL. The dev shell
supports only HTTP and HTTPS. Other schemes return invalid_url without showing a prompt.
Production Notion also applies its existing URL sanitizer.
Documentation
These docs ship with the package and are available from node_modules:
docs/bindings.md: Connect blocks to data sources. The page covers automatic mapping, compatibility, initialization, and live rebinding.docs/data-sources.md: Define local data sources indata/*.json. The page covers value shapes, validation, and files generated from worker schemas.
The shared guides also include host integration documentation for reference.
Use the SDK's public APIs to build blocks. The bridge references below are for debugging communication between the SDK and host and investigating version compatibility.
- Bridge wire protocol: Message identity, validation, and payload semantics.
- Versioning and compatibility: Protocol identifiers and version-change rules.
- Protocol changelog: Breaking changes and SDK release boundaries.
