notion-widget

The complete widget framework: public APIs, a React runtime, Vite tooling, daily development commands, and versioned authoring documentation. The package provides widget discovery, configuration validation, a gallery, an editor, embed pages, and static builds.

Widget authors create a workspace with pnpm create notion-widget and import public APIs from notion-widget. Authoring documentation ships with this package; its installed entry point is node_modules/notion-widget/docs/README.md.

Package boundaries

src/
├── index.ts          # Public entry point for widget APIs and utilities
├── cli.ts            # Argument parsing for dev, build, preview, and check
├── lib/              # Definitions, field validation, appearance, time, and config
├── app/              # React pages, components, routing, and CSS
└── vite/             # Workspace discovery, dev, build, preview, and check
bin.js                # notion-widget command entry point
docs/                 # Authoring docs for the installed version
templates/            # Framework configuration templates

apps/demo depends directly on notion-widget. The independent create-notion-widget initializer creates workspaces and adds notion-widget to their dependencies. The framework package provides the daily notion-widget dev, check, build, and preview commands.

| Import path | Exports | | --- | --- | | notion-widget | defineWidget, field and props types, appearance, time, and configuration utilities | | notion-widget/vite | Workspace development, build, preview, validation, and discovery tools | | notion-widget/client | Type declarations for Vite assets and CSS modules | | notion-widget/tsconfig | Shared TypeScript configuration template for workspaces |

tsdown generates ESM and type declarations in dist/. The package also includes React and CSS source in src/app/ so the workspace's Vite pipeline can process browser code and widget assets. These files are maintained by the framework and are not copied into the author's widgets/ directory.

Development and validation

Run from the monorepo root:

pnpm install
pnpm dev
pnpm typecheck
pnpm lint
pnpm test
pnpm build

pnpm dev builds the framework and initializer, then starts the framework's tsdown watcher and the Vite server for apps/demo. pnpm build:package builds only the framework and initializer; pnpm build also builds the demo into apps/demo/dist/.

After changing public APIs, Vite tooling, or package exports, run pnpm test:package to verify that the framework and initializer tarballs work in a fresh workspace. pnpm test:browser checks demo interactions; pnpm test:package --browser checks development and static site behavior using installed packages.