npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@notionhq/custom-blocks-dev-shell

v0.3.1

Published

Local development shell for Notion custom block workers.

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 dev

Open 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: shell
  • http://chart.localhost:9873: chart block
  • http://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 --json

After 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_name

The -- 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 in data/*.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.