create-ncblock 0.0.39 → 0.0.41

package/templates/worker/_gitignore

@@ -0,0 +1,6 @@
+.env
+.env.*
+dist/
+node_modules/
+workers.*.json
+workers.json

package/templates/worker/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@notionhq/workers-template",
+	"version": "0.0.0",
+	"private": true,
+	"scripts": {
+		"build": "tsc",
+		"check": "tsc --noEmit"
+	},
+	"engines": {
+		"node": ">=22.0.0",
+		"npm": ">=10.9.2"
+	},
+	"devDependencies": {
+		"@types/node": "^22.9.0",
+		"tsx": "^4.20.6",
+		"typescript": "^5.8.0"
+	},
+	"dependencies": {
+		"@notionhq/workers": "file:./notionhq-workers-0.4.0.tgz"
+	},
+	"notionCustomTemplate": {
+		"title": "Worker",
+		"description": "Notion Worker with sync, tool, automation, OAuth, and webhook capability examples."
+	}
+}

package/templates/worker/src/index.ts

@@ -0,0 +1,8 @@
+import { Worker } from "@notionhq/workers"
+
+const worker = new Worker()
+export default worker
+
+worker.customBlock("empty", {
+	path: "./views/empty",
+})

package/templates/worker/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "nodenext",
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"moduleResolution": "nodenext"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,71 @@
+# empty
+
+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`.
+
+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)").
+
+## Data sources
+
+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`:
+
+1. Declare a database with `worker.database(...)`.
+2. Bind it in the `dataSources` map of `worker.customBlock("empty", { path, dataSources: { <viewKey>: <databaseKey> } })`.
+
+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>)`.
+
+## Talking to the host
+
+- 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. Read `node_modules/ncblock/README.md` and the `.d.ts` files for current APIs and signatures.
+
+## Sizing
+
+- The host owns width and height — no hard-coded widths. Layouts must reflow from a phone column to a desktop block.
+- `100vh` ≠ a screen inside an iframe. Use intrinsic sizing with `min-height`.
+- Use container queries (`@container`) — iframe width, not device width, is the real constraint.
+
+## Forbidden APIs
+
+- No top-level navigation, `window.open`, or auth redirects.
+- No network requests. All data comes through host data sources.
+
+## Conventions
+
+- Mount into `<div id="root">` — `useCustomBlockAutoResize` looks for that exact id.
+- `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
+
+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:
+   ```bash
+   git clone https://github.com/makenotion/custom
+   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/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.
+- https://github.com/makenotion/custom — source and examples.

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

@@ -0,0 +1,10 @@
+# empty
+
+Sandbox template for iterating on the SDK's minimal React entry API. Renders a single heading and nothing else.
+
+## Development
+
+```bash
+npm run dev    # Start Vite dev server
+npm run build  # Build to dist/
+```

package/templates/worker/views/empty/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/templates/worker/views/empty/custom_blocks.json

@@ -0,0 +1,4 @@
+{
+	"version": 1,
+	"dataSources": {}
+}

package/templates/worker/views/empty/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<style>
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; }
+</style>
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/src/index.tsx"></script>
+</body>
+</html>

package/templates/worker/views/empty/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "empty",
+	"private": true,
+	"version": "0.0.1",
+	"type": "module",
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"ncblock": "^0.0.36",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5"
+	},
+	"devDependencies": {
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.1",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.10"
+	}
+}

package/templates/worker/views/empty/src/index.css

@@ -0,0 +1,33 @@
+:root {
+	color-scheme: light dark;
+	--background: #ffffff;
+	--foreground: #1f1f1f;
+	--muted: #5f5e5b;
+	--border: #e6e6e6;
+}
+
+@media (prefers-color-scheme: dark) {
+	:root {
+		--background: #191919;
+		--foreground: #f1f1ef;
+		--muted: #b7b6b2;
+		--border: #3f3f3c;
+	}
+}
+
+body {
+	background: var(--background);
+}
+
+main {
+	box-sizing: border-box;
+	padding: 8px 24px;
+	border: 1px solid var(--border);
+	border-radius: 12px;
+	color: var(--foreground);
+	background: var(--background);
+}
+
+p {
+	color: var(--muted);
+}

package/templates/worker/views/empty/src/index.tsx

@@ -0,0 +1,20 @@
+import { NotionCustomBlock } from "ncblock/react"
+import ReactDOM from "react-dom/client"
+import "./index.css"
+
+function App() {
+	return (
+		<main>
+			<h3>empty</h3>
+			<p>
+				Edit <code>src/index.tsx</code> and then deploy using <code>ntn</code>
+			</p>
+		</main>
+	)
+}
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+	<NotionCustomBlock>
+		<App />
+	</NotionCustomBlock>,
+)

package/templates/worker/views/empty/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"types": ["vite/client"],
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx"
+	},
+	"include": ["src", "vite.config.ts"]
+}

package/templates/worker/views/empty/vite.config.ts

@@ -0,0 +1,7 @@
+import react from "@vitejs/plugin-react"
+import { notionCustomBlock } from "ncblock/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+	plugins: [react(), notionCustomBlock()],
+})