@notionhq/custom-blocks-dev-shell 0.1.29 → 0.1.31

package/README.md

@@ -1,50 +1,46 @@
-# Notion custom blocks dev shell
+# 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. Use it to exercise a block locally
-before `ntn workers deploy`.
+The dev shell runs custom blocks in a local mock Notion host. It provides sample
+data that blocks can use. It builds the worker, finds its custom block
+declarations, and serves each block with the worker's Vite server. Use it before
+`ntn workers deploy`.
+
+Three groups use this dev shell:
+
+- Custom block authors use it to build and preview custom blocks.
+- Custom block SDK authors use it to develop and test the SDK.
+- The verification harness uses it to check SDK and host behavior.
 
 ## Usage
 
-From anywhere inside your worker project, with the Notion CLI (v0.20.0+):
+From your worker project, with Notion CLI `0.20.0` or later:
 
 ```bash
 ntn customblocks dev
 ```
 
-Then open http://localhost:9873.
+Then open `http://localhost:9873`.
 
-Add this package to the worker's `devDependencies` to pin its version and make
-the reference docs below readable from the worker's `node_modules`; without an
-install, the CLI fetches the latest release on each run instead.
+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.
 
-Options:
+### 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).
+- `[path]`: Select a worker directory instead of using the current directory.
+- `--port <port>`: Use a different port for the dev shell. The default is
+  `9873`.
+- `--block-base-port <port>`: Set the first port for block servers. The default
+  is `9876`. Each next block uses the next port.
 
-## Reference
+## Documentation
 
-One page per topic, shipped in this package's `docs/` so they're readable
-from `node_modules`:
+These docs ship with the package and are available from `node_modules`:
 
-- [`docs/bindings.md`](./docs/bindings.md) — connecting blocks to data
-  sources: auto-mapping and compatibility rules, initialization, and live
+- [`docs/bindings.md`](./docs/bindings.md): Connect blocks to data sources.
+  The page covers automatic mapping, compatibility, initialization, and live
   rebinding.
-- [`docs/data-sources.md`](./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`.
+- [`docs/data-sources.md`](./docs/data-sources.md): Define local data sources
+  in `src/data/*.json`. The page covers value shapes, validation, and files
+  generated from worker schemas.