@notionhq/custom-blocks 0.1.11 → 0.1.13

package/README.md

@@ -104,7 +104,6 @@ API surface, one page per category. Import framework-neutral APIs from `@notionh
 - [`docs/users.md`](./docs/users.md) — `users.list / get`, the `NotionUser` shape, paging.
 - [`docs/errors.md`](./docs/errors.md) — request results, error format, error codes, retries, and initialization failures.
 - [`docs/deployment.md`](./docs/deployment.md) — worker-backed deploys, localhost self-hosted fallback, where the manifest comes from.
-- [`docs/vite-plugin.md`](./docs/vite-plugin.md) — the `notionCustomBlock()` Vite plugin.
 
 ## Forbidden APIs
 

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.11"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.13"

package/docs/deployment.md

@@ -1,39 +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.
 
-For everyday local development you usually don't need to wire this up yourself: `ntn customblocks dev` runs the custom blocks dev shell, which serves the worker's blocks this way and renders them in a mock Notion 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.11",
+	"version": "0.1.13",
 	"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

@@ -1,46 +1,8 @@
-/**
- * Type declarations for the Vite plugin. The runtime lives in `vite.js` —
- * see that file for behavior, options, and the reasoning for splitting `.js`
- * + `.d.ts` instead of using a single `.ts` source.
- */
-
-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.
+ * @deprecated This compatibility stub does nothing. Remove it from Vite config when possible.
  */
 export function notionCustomBlock(): NotionCustomBlockPlugin

package/vite-plugin/index.js

@@ -1,116 +1,8 @@
+// Compatibility export for existing blocks.
+// TODO(custom-blocks): Remove the Vite server entirely when bumping bridge protocol version.
 /**
- * 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.
- *
- * 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
- * config loader resolves this subpath through Node's ESM resolver, which
- * can't load `.ts` source files. Lives in its own `vite-plugin/` directory
- * so it can grow its own tsconfig later.
- *
- * Usage:
- *
- *   import { notionCustomBlock } from "@notionhq/custom-blocks/vite"
- *
- *   export default defineConfig({
- *     plugins: [react(), notionCustomBlock()],
- *   })
- *
- * Requires `"type": "module"` in the consuming project's `package.json` so
- * 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.
+ * @deprecated This compatibility stub does nothing. Remove it from Vite config when possible.
  */
-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",
-		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/
-			// so all asset URLs in the built bundle must be relative.
-			// Force `base: "./"` and reject any other explicit value
-			//
-			// Note: once we are set up with a wildcard subdomain host, this will no longer be necessary
-			// and should be removed, since /assets will work fine.
-			if (userConfig.base !== undefined && userConfig.base !== REQUIRED_BASE) {
-				throw new Error(
-					`@notionhq/custom-blocks/vite: \`base\` must be "${REQUIRED_BASE}" (got ${JSON.stringify(userConfig.base)}). Custom blocks need relative asset paths so the bundle works under any host-served prefix.`,
-				)
-			}
-			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,
-			})
-		},
-	}
+	return { name: "custom-blocks:legacy-vite-plugin" }
 }

package/docs/vite-plugin.md

@@ -1,22 +0,0 @@
-# Vite plugin
-
-The `notionCustomBlock()` plugin from `@notionhq/custom-blocks/vite` wires a block's local dev server and build output to the SDK handshake.
-
-```ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import { notionCustomBlock } from "@notionhq/custom-blocks/vite";
-
-export default defineConfig({
-  plugins: [react(), notionCustomBlock()],
-});
-```
-
-It does two things:
-
-- **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.