create-ncblock 0.0.40 → 0.0.42

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-ncblock",
-	"version": "0.0.40",
+	"version": "0.0.42",
 	"description": "Create a Notion custom view block project.",
 	"type": "module",
 	"bin": {

package/scripts/init.ts

@@ -18,6 +18,7 @@ import { resolveInitArgs } from "./utils/resolveInitArgs"
 import {
 	getTemplateByName,
 	getTemplates,
+	isWorkerTemplate,
 	scaffoldTemplate,
 	type TemplateMetadata,
 } from "./utils/templates"
@@ -542,6 +543,7 @@ async function main() {
 	)
 	const dest = resolve(dir)
 	const templateDir = resolve(templateBaseDir, selectedTemplate.name)
+	const workerShaped = isWorkerTemplate(templateDir)
 
 	const destNonEmpty = existsSync(dest) && readdirSync(dest).length > 0
 	if (destNonEmpty) {
@@ -578,7 +580,10 @@ async function main() {
 	// downstream walks a positional block/view ID up to its parent database.
 	const blockIdArg = args.block as string | undefined
 	const promptedCollection =
-		args.collection === undefined && blockIdArg === undefined && installDeps
+		!workerShaped &&
+		args.collection === undefined &&
+		blockIdArg === undefined &&
+		installDeps
 			? (await ask("Database URL/ID (enter to skip):", "skip")).trim()
 			: undefined
 	const collectionOverride =
@@ -640,12 +645,14 @@ async function main() {
 		step("Initialized git repo")
 	}
 
-	writeInitialTarget(dest, { env: resolved.env, blockId })
-	step(`Seeded .notion/target.json`)
-	if (classified?.kind === "view") {
-		console.log(
-			`    ${c.dim}(view ID resolved — using as block id, database ${databaseId ?? "(none)"})${c.reset}`,
-		)
+	if (!workerShaped) {
+		writeInitialTarget(dest, { env: resolved.env, blockId })
+		step(`Seeded .notion/target.json`)
+		if (classified?.kind === "view") {
+			console.log(
+				`    ${c.dim}(view ID resolved — using as block id, database ${databaseId ?? "(none)"})${c.reset}`,
+			)
+		}
 	}
 
 	let connected = false
@@ -660,7 +667,7 @@ async function main() {
 		execSync(`${pm} ${installArgs}`, { cwd: dest, stdio: "inherit" })
 		step("Installed dependencies")
 
-		if (databaseId) {
+		if (databaseId && !workerShaped) {
 			console.log("")
 			try {
 				runNcblock(dest, ["connect", databaseId, "--quiet"])
@@ -676,8 +683,6 @@ async function main() {
 		}
 	}
 
-	const deployCommand = blockId ? `npx ncblock deploy dist/` : undefined
-
 	console.log(`\n${c.bold}  Ready!${c.reset} Next steps:\n`)
 	if (dest !== resolve(".")) {
 		console.log(`  cd ${formatShellPath(dest)}`)
@@ -685,22 +690,33 @@ async function main() {
 	if (!installDeps) {
 		console.log(`  ${pm} install`)
 	}
-	console.log(`  ${pm} run build`)
-	if (deployCommand) {
-		console.log(`  ${deployCommand}`)
+
+	if (workerShaped) {
+		// Workers build and bind their views/data sources as part of deploy; data
+		// sources are wired in code (see AGENTS.md). Carry a non-prod env through.
+		const envFlag =
+			resolved.env === "production" ? "" : ` --env=${resolved.env}`
+		console.log(`  ntn${envFlag} workers deploy`)
+		console.log("")
 	} else {
-		console.log(
-			`\n  Then, go back to the instructions in Notion and paste the ${c.bold}ntn deploy${c.reset} command.`,
-		)
-	}
+		const deployCommand = blockId ? `npx ncblock deploy dist/` : undefined
+		console.log(`  ${pm} run build`)
+		if (deployCommand) {
+			console.log(`  ${deployCommand}`)
+		} else {
+			console.log(
+				`\n  Then, go back to the instructions in Notion and paste the ${c.bold}ntn deploy${c.reset} command.`,
+			)
+		}
 
-	if (installDeps && !connected) {
-		console.log(
-			`\n  ${c.yellow}No data source connected yet.${c.reset} To wire one up:`,
-		)
-		console.log(`    npx ncblock connect <database-url-or-id>`)
+		if (installDeps && !connected) {
+			console.log(
+				`\n  ${c.yellow}No data source connected yet.${c.reset} To wire one up:`,
+			)
+			console.log(`    npx ncblock connect <database-url-or-id>`)
+		}
+		console.log("")
 	}
-	console.log("")
 
 	closePromptInterface()
 }

package/scripts/utils/templates.ts

@@ -117,6 +117,17 @@ export function getTemplateByName(
 	)
 }
 
+// A template is worker-backed if @notionhq/workers is in its dependencies.
+export function isWorkerTemplate(templateDir: string): boolean {
+	const pkgPath = resolve(templateDir, "package.json")
+	if (!existsSync(pkgPath)) {
+		return false
+	}
+	return Boolean(
+		readTemplatePackageJson(pkgPath).dependencies?.["@notionhq/workers"],
+	)
+}
+
 type ScaffoldTemplateOptions = {
 	root: string
 	templateDir: string
@@ -217,6 +228,10 @@ function applyTemplateReplacements(
 	return replaced
 }
 
+function firstExisting(paths: string[]): string | undefined {
+	return paths.find(path => existsSync(path))
+}
+
 function writeRenderedFile(args: {
 	sourcePath: string
 	targetPath: string
@@ -293,14 +308,25 @@ export function scaffoldTemplate({
 		})
 	}
 
+	// Worker templates ship their own AGENTS.md (a symlink to
+	// .agents/INSTRUCTIONS.md). copyDirectoryContents skips symlinks, and
+	// `npm publish` strips them from the package entirely, so prefer the
+	// symlink target's real file and fall back to the symlink for local runs.
 	const agentsTarget = resolve(dest, "AGENTS.md")
 	if (overwrite || !existsSync(agentsTarget)) {
-		const agentsSource = resolve(root, "scripts/scaffold-assets/AGENTS.md")
-		writeRenderedFile({
-			sourcePath: agentsSource,
-			targetPath: agentsTarget,
-			replacements,
-		})
+		const agentsSource = isWorkerTemplate(templateDir)
+			? firstExisting([
+					resolve(templateDir, ".agents/INSTRUCTIONS.md"),
+					resolve(templateDir, "AGENTS.md"),
+				])
+			: resolve(root, "scripts/scaffold-assets/AGENTS.md")
+		if (agentsSource) {
+			writeRenderedFile({
+				sourcePath: agentsSource,
+				targetPath: agentsTarget,
+				replacements,
+			})
+		}
 	}
 
 	const pkgPath = resolve(dest, "package.json")

package/sdk-version.json

@@ -1 +1 @@
-{"version":"0.0.40"}
+{"version":"0.0.42"}

package/templates/worker/.agents/INSTRUCTIONS.md

@@ -5,6 +5,7 @@ Overall workers documentation lives at https://developers.notion.com/workers/get
 ## Project Structure & Module Organization
 - `src/index.ts` defines the worker and capabilities.
 - `.examples/` has focused samples (sync, tool, automation, OAuth, webhook).
+- `views/` holds custom-block views (frontend React apps) shipped by the worker. Each view is its own buildable project (`views/<name>/`) with its own `AGENTS.md` describing how to author it. See [Custom blocks (views)](#custom-blocks-views).
 - Shared agent skills live in `.agents/skills/`. `.claude/skills` is kept as a compatibility symlink for Claude-specific discovery.
 - Generated: `dist/` build output, `workers.json` CLI config.
 
@@ -72,6 +73,12 @@ worker.webhook("onGithubPush", {
 		}
 	},
 });
+
+// Ship a frontend view (custom block) rendered inside a Notion block.
+// The view lives in views/dashboard/ and deploys with the worker.
+worker.customBlock("dashboard", {
+	path: "./views/dashboard",
+});
 ```
 
 ### Notion API access (`context.notion`)
@@ -367,6 +374,56 @@ This full URL can be retrieved using the `ntn workers webhooks list` command.
 
 It is also the responsibility of the worker to verify the webhook. Throw `WebhookVerificationError` if the payload is not valid. 5 invalid payloads in a row will cause webhooks to short circuit until redeployed.
 
+### Custom blocks (views)
+
+A custom block is a **frontend view** — a sandboxed React app rendered inside a Notion block. It ships *with* the worker: there is no separate CLI. `ntn workers deploy` builds the view, bundles it, and binds its data sources in one step. **Do not use the `ncblock` CLI here** (e.g. `npx ncblock connect` / `deploy`) — that flow is for standalone custom-block projects and does not apply inside a worker.
+
+Declare a view with `worker.customBlock(key, config)` in `src/index.ts`:
+
+```ts
+worker.customBlock("dashboard", {
+	path: "./views/dashboard", // buildable project dir, relative to the worker root
+});
+```
+
+- `type` defaults to `"project"`: the view is built by running its `command` (default `npm run build`) and its `output` dir (default `dist`) is bundled. Pass `type: "static"` to serve an already-built directory with no build step.
+- The view itself is a separate project under `views/<name>/`. Author it there — see `views/<name>/AGENTS.md` for the frontend rules (React hooks, sizing, forbidden APIs). It uses the `ncblock` package (React hooks + Vite plugin), which is the SDK surface, not the CLI.
+
+#### Wiring data sources
+
+A view reads data through **managed databases declared in the worker**, not through `ncblock connect`. Declare the database with `worker.database(...)`, then bind it in the `dataSources` map (data-source key → database key). The server binds the block to that managed database on deploy, and the SDK generates the view's `custom_blocks.json` from this declaration — so any hand-written or `ncblock connect`-generated `custom_blocks.json` in the view is ignored.
+
+```ts
+const issues = worker.database("issues", {
+	type: "managed",
+	initialTitle: "Issues",
+	primaryKeyProperty: "Issue ID",
+	schema: { properties: { Title: Schema.title(), "Issue ID": Schema.richText() } },
+});
+
+worker.sync("issuesSync", { database: issues, execute: async () => { /* ... */ } });
+
+worker.customBlock("dashboard", {
+	path: "./views/dashboard",
+	// Bind the view's "issues" data-source key to the managed `issues` database.
+	dataSources: { issues: "issues" },
+});
+```
+
+Inside the view, read that data source with the `ncblock` hooks (e.g. `useDataSource("issues")`). A view with no `dataSources` is fine — it just renders without host data.
+
+#### Developing and deploying
+
+```shell
+# Iterate on the view locally (run inside views/<name>/):
+npm run dev          # Vite dev server; preview against a live or mock Notion host
+
+# Build + deploy the worker and all its views together:
+ntn workers deploy
+```
+
+See `views/<name>/AGENTS.md` for preview options (live Notion host vs. mock dev shell).
+
 ### Sync Management (CLI)
 
 **Monitor sync status:**

package/templates/worker/views/empty/AGENTS.md

@@ -2,30 +2,23 @@
 
 A **Notion custom view** — a sandboxed `<iframe>` rendered inside a Notion block. The iframe is the entire viewport; the only channel to the host is a `postMessage` bridge wrapped by `ncblock`.
 
-## Connecting to a Notion database
+This view ships as part of a **worker**: it is declared with `worker.customBlock("empty", { path: "./views/empty" })` in the worker's `src/index.ts`, and it builds and deploys together with the worker via `ntn workers deploy`. There is **no separate `ncblock` CLI step** — do not run `npx ncblock connect` / `deploy`. This file covers how to author the view; for how the worker wires and deploys it, see the worker's `AGENTS.md` ("Custom blocks (views)").
 
-If `custom_blocks.json` or `.notion/target.json` doesn't yet reference a datasource, ask the user if they want to connect a database by url or id, then run:
+## Data sources
 
-```bash
-npx ncblock connect <database-url-or-id>
-```
+This view reads data from **managed databases declared in the worker**, not from a database you connect here. Wiring happens in the worker's `src/index.ts`:
 
-That writes `custom_blocks.json`, `.notion/target.json`, and PATCHes any blocks already listed there. Discover other commands with `npx ncblock --help`.
-
-## Talking to the host
+1. Declare a database with `worker.database(...)`.
+2. Bind it in the `dataSources` map of `worker.customBlock("empty", { path, dataSources: { <viewKey>: <databaseKey> } })`.
 
-- Always use the React hooks from `ncblock`. Never call `window.parent.postMessage` directly — the SDK owns the protocol.
-- Render app code inside `<NotionCustomBlock>` so the handshake completes before hooks like `useTheme` or `useCustomBlockContext` run.
+The worker generates this view's `custom_blocks.json` from that declaration on deploy, so don't hand-edit it (or run `ncblock connect`) — those changes are ignored. Inside the view, read a bound data source with `useDataSource(<viewKey>)`.
 
-Hooks at a glance:
+## Talking to the host
 
-- `useCustomBlockContext()` — `{ customBlockId, parent, page }`.
-- `useTheme()` — `"light" | "dark"`.
-- `useDataSource(key, initialLimit?)` — `{ items, isLoading, hasMore, fetchMore, error }`.
-- `useManifest()` — the declared manifest: data-source keys plus their property declarations.
-- `pages.create(input)` — creates a page; pass `parent: { type: "data_source_key", key }` to target the block's wired data source.
+- Always use the React hooks from `ncblock/react`. Never call `window.parent.postMessage` directly — the SDK owns the protocol.
+- Render app code inside `<NotionCustomBlock>` so the handshake completes before hooks like `useTheme` or `useBlockId` run.
 
-`<NotionCustomBlock>` runs `useCustomBlockAutoResize` for you by default — no extra wiring needed. Pass `autoResize={false}` for full-bleed views. Full signatures live in `node_modules/ncblock/docs/*.md` and the `.d.ts` files.
+`<NotionCustomBlock>` runs `useCustomBlockAutoResize` for you by default — no extra wiring needed. Pass `autoResize={false}` for full-bleed views. Read `node_modules/ncblock/README.md` and the `.d.ts` files for current APIs and signatures.
 
 ## Sizing
 
@@ -41,11 +34,17 @@ Hooks at a glance:
 ## Conventions
 
 - Mount into `<div id="root">` — `useCustomBlockAutoResize` looks for that exact id.
-- `custom_blocks.json` at the project root defines the data contract. The SDK's Vite plugin serves it in dev; `ntn` bundles it into the deploy.
+- `custom_blocks.json` is the data contract. The SDK's Vite plugin serves it in dev; in a worker it is **generated** from the worker's `worker.customBlock(...)` declaration at deploy time.
 
 ## Previewing during development
 
-Two options:
+Run the Vite dev server from this view's directory:
+
+```bash
+npm run dev   # http://localhost:5173
+```
+
+Then preview against a host:
 
 1. **Live Notion host** — ask the user to create a block via `/custom` and paste the Vite dev URL (e.g. `http://localhost:5173`) into the block's URL field.
 2. **Mock host** — run the dev shell in another tab:
@@ -54,14 +53,19 @@ Two options:
    cd custom && pnpm install && pnpm run dev:shell   # http://localhost:9875
    ```
 
+When the view is ready, deploy it with the worker from the worker root:
+
+```bash
+ntn workers deploy
+```
+
 ## Where to look next
 
 - `node_modules/ncblock/README.md` — landing page with a TOC into the per-category docs below.
 - `node_modules/ncblock/docs/lifecycle.md` — `<NotionCustomBlock>`, init, sizing, auto-resize.
-- `node_modules/ncblock/docs/context.md` — `useCustomBlockContext`, `useTheme`.
+- `node_modules/ncblock/docs/block-location.md` — `useBlockId`, `useParent`, `usePage`, `useTheme`.
 - `node_modules/ncblock/docs/data-sources.md` — `useDataSource`, row/property/date types, worked example.
 - `node_modules/ncblock/docs/pages.md` — `pages.create / get / update / delete`.
 - `node_modules/ncblock/docs/users.md` — `users.list / get`, `NotionUser`.
 - `node_modules/ncblock/docs/manifest.md` — `custom_blocks.json` + Vite plugin.
-- `node_modules/ncblock/dist/*.d.ts` — typed surface; hover in your editor.
 - https://github.com/makenotion/custom — source and examples.