@notionhq/custom-blocks 0.1.10 → 0.1.12

package/README.md

@@ -15,7 +15,11 @@ the workspace. React is optional unless the block imports
 `@notionhq/custom-blocks/react`. React blocks need `react` and `react-dom`.
 
 For local preview, run `ntn customblocks dev` from the worker project, then
-open `http://localhost:9873`.
+open `http://localhost:9873`. Install
+[`@notionhq/custom-blocks-dev-shell`](https://www.npmjs.com/package/@notionhq/custom-blocks-dev-shell)
+as a devDependency to pin the shell and get its reference docs in
+`node_modules`; see [`docs/deployment.md`](./docs/deployment.md) for how local
+serving works.
 
 ## Quick start
 

package/dist/bridge/loadManifest.d.ts

@@ -10,12 +10,11 @@ export type ManifestLoadResult = {
     error: CustomBlockConnectError;
 };
 /**
- * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
- * `/custom_blocks.json`. This is to support local development where the block is served from a
- * local dev server.
+ * On the literal `localhost` hostname, attempts to load the custom block's optional self-hosted
+ * manifest exposed by the worker dev shell at `/manifest`.
  *
  * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export declare function attemptToLoadSelfHostedManifest(): Promise<ManifestLoadResult>;
+export declare function attemptToLoadSelfHostedManifest(hostname?: string | undefined): Promise<ManifestLoadResult>;
 export {};
 //# sourceMappingURL=loadManifest.d.ts.map

package/dist/bridge/loadManifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadManifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/loadManifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AACtF,OAAO,EACN,KAAK,mBAAmB,EAExB,MAAM,8CAA8C,CAAA;AAKrD,KAAK,2BAA2B,GAC7B,sBAAsB,GACtB,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,KAAK,uBAAuB,GAAG,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAEhF,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;CAChB,GACD;IACA,QAAQ,EAAE,IAAI,CAAA;IACd,KAAK,EAAE,uBAAuB,CAAA;CAC7B,CAAA;AAEJ;;;;;;GAMG;AACH,wBAAsB,+BAA+B,IAAI,OAAO,CAAC,kBAAkB,CAAC,CA0DnF"}
+{"version":3,"file":"loadManifest.d.ts","sourceRoot":"","sources":["../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/loadManifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AACtF,OAAO,EACN,KAAK,mBAAmB,EAExB,MAAM,8CAA8C,CAAA;AAKrD,KAAK,2BAA2B,GAC7B,sBAAsB,GACtB,kBAAkB,GAClB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,KAAK,uBAAuB,GAAG,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AAEhF,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;CAChB,GACD;IACA,QAAQ,EAAE,IAAI,CAAA;IACd,KAAK,EAAE,uBAAuB,CAAA;CAC7B,CAAA;AAEJ;;;;;GAKG;AACH,wBAAsB,+BAA+B,CACpD,QAAQ,GAAE,MAAM,GAAG,SAEQ,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAgE7B"}

package/dist/bridge/loadManifest.js

@@ -1,14 +1,20 @@
 import { manifestSchema, } from "../protocol/manifest.js";
 import * as v from "valibot";
-const MANIFEST_URL = "custom_blocks.json";
+const MANIFEST_URL = "/manifest";
 /**
- * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
- * `/custom_blocks.json`. This is to support local development where the block is served from a
- * local dev server.
+ * On the literal `localhost` hostname, attempts to load the custom block's optional self-hosted
+ * manifest exposed by the worker dev shell at `/manifest`.
  *
  * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export async function attemptToLoadSelfHostedManifest() {
+export async function attemptToLoadSelfHostedManifest(hostname = typeof window === "undefined"
+    ? undefined
+    : window.location.hostname) {
+    // Runtime manifests are a localhost-only development fallback. Deployed
+    // blocks receive their authoritative manifest from the host during init.
+    if (hostname !== "localhost") {
+        return { manifest: null };
+    }
     let response;
     try {
         response = await fetch(MANIFEST_URL, { credentials: "omit" });

package/dist/init.js

@@ -39,7 +39,7 @@ export function initCustomBlock(opts = {}) {
 }
 /**
  * Performs the host <-> sandbox SDK handshake:
- * 1. Attempts to load an optional self-hosted `custom_blocks.json`
+ * 1. On localhost, attempts to load the worker manifest from `/manifest`
  * 2. Sends `connect` with the manifest
  * 3. Awaits the host's `init` message
  * 4. Applies the `init` payload and acknowledges with `initResult` (fire-and-forget)

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.10"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.12"

package/docs/deployment.md

@@ -1,37 +1,17 @@
 # Deployment and manifests
 
-A custom block is a static web bundle — an `index.html` plus optional assets — that Notion loads into a sandboxed `<iframe>`, so the bundle needs to be hosted somewhere Notion can reach. Notion does that hosting: the block ships as part of a worker. Declare the block source and data source schema with `worker.customBlock(...)` in the worker's `src/index.ts`, deploy with `ntn workers deploy`, and Notion serves the built bundle. Serving the bundle from your own dev server is provided as a local-development fallback, not an officially supported deployment target.
+A custom block is a static web bundle — an `index.html` plus optional assets — that Notion loads into a sandboxed `<iframe>`. Custom blocks ship as part of a worker: declare the block source and data source schema with `worker.customBlock(...)` in the worker's `src/index.ts`, deploy with `ntn workers deploy`, and Notion serves the built bundle.
 
-The difference between the two paths is where the manifest lives:
+A custom block manifest describes the data sources a block requires, including their semantic keys, display metadata, and property schemas. The block's `worker.customBlock(...)` declaration is the manifest's single source of truth:
 
-- **Worker-backed** — deploying persists the manifest on the block's definition record in Notion. The host reads it from there. The bundle carries no manifest.
-- **Self-hosted (localhost)** — there is no persisted record, so the block serves its manifest dynamically at `/custom_blocks.json` and passes the manifest to the host in the `connect` handshake.
+- **Deployed** — deploying persists the manifest on the block's definition record in Notion. The host reads it from there and sends it to the SDK during initialization.
+- **Local development** — the dev shell extracts the same worker declaration at runtime and serves the selected block's manifest dynamically at `/manifest`.
 
-For a self-hosted block, the sandbox can propose the initial manifest in `connect`. The host decides whether to use it and sends the authoritative manifest back in `init`. The SDK always uses the host-provided manifest from `init` even if it differs from the one sent during `connect`.
+## Local development
 
-## Self-hosted blocks (localhost fallback)
+Run `ntn customblocks dev` from a worker. It builds the worker, extracts its custom block declarations, starts one localhost Vite server per block, and renders them in the mock host at http://localhost:9873.
 
-During development, a Notion host can point a custom block at a local dev server instead of a deployed worker. The block describes itself with an optional `custom_blocks.json` at the bundle root:
-
-```json
-{
-  "version": 1,
-  "dataSources": {
-    "tasks": {
-      "name": "Tasks",
-      "description": "The collection of tasks to render",
-      "properties": {
-        "title": { "name": "Title", "type": "title" },
-        "dueDate": { "name": "Due date", "type": "date" }
-      }
-    }
-  }
-}
-```
-
-At startup the SDK fetches this file from the bundle's origin and forwards it in `connect`. If the file is missing, the SDK omits `manifest` from `connect`. If it is present but unreadable or invalid, initialization fails.
-
-The [Vite plugin](./vite-plugin.md) keeps this file working in dev and emits it into `dist/` on build.
+At startup, the SDK fetches `/manifest` only when the bundle's hostname is exactly `localhost`, then forwards the response in `connect`. On every other hostname, the SDK skips this fetch and relies on the host-provided manifest from `init`.
 
 ## Types
 

package/docs/vite-plugin.md

@@ -1,6 +1,6 @@
 # Vite plugin
 
-The `notionCustomBlock()` plugin from `@notionhq/custom-blocks/vite` wires a block's local dev server and build output to the SDK handshake.
+The `notionCustomBlock()` plugin from `@notionhq/custom-blocks/vite` configures a block's build output for Notion hosting.
 
 ```ts
 import { defineConfig } from "vite";
@@ -12,11 +12,6 @@ export default defineConfig({
 });
 ```
 
-It does two things:
+It forces `base: "./"` and rejects any other explicit value. Custom blocks are served from a content-addressed path, so asset URLs in the built bundle must be relative.
 
-- **Forces `base: "./"`** (and rejects any other explicit value). Custom blocks are served from a content-addressed path, so asset URLs in the built bundle must be relative.
-- **Passes through `custom_blocks.json`** when the optional file exists in the project root: served by middleware in dev so HMR and the SDK handshake see the same file, and emitted into `dist/` as a separate asset on `vite build`.
-
-The `custom_blocks.json` manifest file only applies when a block is served from `localhost` during development instead of deployed as a worker. Worker-backed blocks declare their manifest with `worker.customBlock(...)` and should not maintain a `custom_blocks.json`, but they still use the plugin for the `base` enforcement. See [deployment.md](./deployment.md) for more information.
-
-The plugin does not validate the manifest. The SDK validates it on receipt.
+The plugin does not serve or emit manifests. Declare the manifest with `worker.customBlock(...)`; the worker dev shell exposes it dynamically at `/manifest` during local development. See [deployment.md](./deployment.md) for more information.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.10",
+	"version": "0.1.12",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/bridge/loadManifest.ts

@@ -5,7 +5,7 @@ import {
 } from "@notionhq/custom-blocks-protocol/manifest.js"
 import * as v from "valibot"
 
-const MANIFEST_URL = "custom_blocks.json"
+const MANIFEST_URL = "/manifest"
 
 type CustomBlockConnectErrorCode =
 	| "manifest_unavailable"
@@ -25,13 +25,22 @@ export type ManifestLoadResult =
 	  }
 
 /**
- * Attempts to load the custom block's optional self-hosted manifest, co-located with the bundle at
- * `/custom_blocks.json`. This is to support local development where the block is served from a
- * local dev server.
+ * On the literal `localhost` hostname, attempts to load the custom block's optional self-hosted
+ * manifest exposed by the worker dev shell at `/manifest`.
  *
  * It is up to the host to decide whether to use this manifest or provide its own persisted manifest.
  */
-export async function attemptToLoadSelfHostedManifest(): Promise<ManifestLoadResult> {
+export async function attemptToLoadSelfHostedManifest(
+	hostname: string | undefined = typeof window === "undefined"
+		? undefined
+		: window.location.hostname,
+): Promise<ManifestLoadResult> {
+	// Runtime manifests are a localhost-only development fallback. Deployed
+	// blocks receive their authoritative manifest from the host during init.
+	if (hostname !== "localhost") {
+		return { manifest: null }
+	}
+
 	let response: Response
 	try {
 		response = await fetch(MANIFEST_URL, { credentials: "omit" })

package/src/init.ts

@@ -83,7 +83,7 @@ export function initCustomBlock(
 
 /**
  * Performs the host <-> sandbox SDK handshake:
- * 1. Attempts to load an optional self-hosted `custom_blocks.json`
+ * 1. On localhost, attempts to load the worker manifest from `/manifest`
  * 2. Sends `connect` with the manifest
  * 3. Awaits the host's `init` message
  * 4. Applies the `init` payload and acknowledges with `initResult` (fire-and-forget)

package/vite-plugin/index.d.ts

@@ -6,41 +6,12 @@
 
 type UserConfig = { base?: string }
 
-type ResolvedConfig = { root: string; command: "serve" | "build" }
-
-type ServerLike = {
-	middlewares: { use: (handler: MiddlewareHandler) => unknown }
-}
-
-type MiddlewareHandler = (
-	req: { url?: string },
-	res: {
-		statusCode?: number
-		setHeader: (name: string, value: string) => void
-		end: (body?: string) => void
-	},
-	next: () => void,
-) => void
-
-type AssetEmitterContext = {
-	emitFile: (file: {
-		type: "asset"
-		fileName: string
-		source: string
-	}) => string
-}
-
 export type NotionCustomBlockPlugin = {
 	name: string
 	config: (userConfig: UserConfig) => { base: string }
-	configResolved: (config: ResolvedConfig) => void
-	configureServer: (server: ServerLike) => void
-	configurePreviewServer: (server: ServerLike) => void
-	buildStart: (this: AssetEmitterContext) => void
 }
 
 /**
- * Vite plugin that serves an optional self-hosted `custom_blocks.json` to the custom block
- * bundle during local development and emits it as a separate asset on build.
+ * Vite plugin that configures relative asset paths for custom block bundles.
  */
 export function notionCustomBlock(): NotionCustomBlockPlugin

package/vite-plugin/index.js

@@ -1,7 +1,5 @@
 /**
- * Vite plugin half of `@notionhq/custom-blocks`. Exposes an optional
- * self-hosted `custom_blocks.json` manifest to the custom-block bundle so the
- * SDK's runtime fetch can resolve.
+ * Vite plugin half of `@notionhq/custom-blocks`.
  *
  * Authored as plain JS (with `index.d.ts` co-located for types) — the rest of
  * the SDK is `.ts` consumed directly via the workspace symlink, but Vite's
@@ -21,56 +19,14 @@
  * Vite's config loader uses Node's ESM resolver (not CommonJS `require`,
  * which fails for ESM-only deps).
  *
- * - **Dev (`vite`)** — middleware serves `/custom_blocks.json` from the project root
- *   when the optional file exists.
- * - **Build (`vite build`)** — emits an existing `custom_blocks.json` as an asset
- *   alongside the built `index.html` so `vite preview` and any local file server
- *   can serve it.
- *
- * Validation is intentionally not performed here — the SDK validates on
- * receipt, and the CLI validates separately at deploy time.
+ * The worker dev shell owns the localhost `/manifest` route. This plugin only
+ * controls bundle asset paths.
  */
-import { existsSync, readFileSync } from "node:fs"
-import { resolve } from "node:path"
-
-const MANIFEST_FILENAME = "custom_blocks.json"
-const MANIFEST_URL_PATH = `/${MANIFEST_FILENAME}`
 const REQUIRED_BASE = "./"
 
 export function notionCustomBlock() {
-	let projectRoot = process.cwd()
-	let command = "serve"
-
-	function manifestPath() {
-		return resolve(projectRoot, MANIFEST_FILENAME)
-	}
-
-	function readManifest() {
-		const file = manifestPath()
-		if (!existsSync(file)) {
-			return undefined
-		}
-		return readFileSync(file, "utf8")
-	}
-
-	function middleware(req, res, next) {
-		const path = req.url?.split("?", 1)[0]
-		if (path !== MANIFEST_URL_PATH) {
-			next()
-			return
-		}
-		const contents = readManifest()
-		if (contents === undefined) {
-			res.statusCode = 404
-			res.end()
-			return
-		}
-		res.setHeader("Content-Type", "application/json")
-		res.end(contents)
-	}
-
 	return {
-		name: "custom-blocks:notion-manifest",
+		name: "custom-blocks:bundle-base",
 		config(userConfig) {
 			// Custom blocks are served from a content-addressed path that
 			// has trailing slashes, eg https://dev.notion.so/custom-block-bundle/357b35e6-e67f-81fd-b425-00e7b3e2afd1/
@@ -86,31 +42,5 @@ export function notionCustomBlock() {
 			}
 			return { base: REQUIRED_BASE }
 		},
-		configResolved(config) {
-			projectRoot = config.root
-			command = config.command
-		},
-		configureServer(server) {
-			server.middlewares.use(middleware)
-		},
-		configurePreviewServer(server) {
-			server.middlewares.use(middleware)
-		},
-		buildStart() {
-			// `emitFile` is only valid during `vite build`. In serve mode the
-			// middleware above handles `/custom_blocks.json`, so we skip emission.
-			if (command !== "build") {
-				return
-			}
-			const contents = readManifest()
-			if (contents === undefined) {
-				return
-			}
-			this.emitFile({
-				type: "asset",
-				fileName: MANIFEST_FILENAME,
-				source: contents,
-			})
-		},
 	}
 }