CLI reference

npm create grist-widget

npm create grist-widget my-widget
cd my-widget
pnpm install
pnpm dev

The template is embedded directly in the CLI — nothing is fetched from GitHub at scaffold time. It's the same starting point as grist-widget-template (what the quickstart's "Copy this starter repo" path gives you), so both paths converge on identical code.

What you get

• index.html with the grist-plugin-api.js script tag wired in.
• src/main.tsx mounting the React root.
• src/App.tsx showing the provider + boundary + useGrist() pattern, with placeholder UI you can immediately replace.
• Tailwind preconfigured for theme-aware widgets (light / dark / system).
• A vitest setup that imports renderWithGrist from grist-widget-sdk/emulator/testing.
• Prettier + ESLint with project-wide rules.

After scaffolding, the first edit is typically src/App.tsx — replace the placeholder with the widget you want. The Cookbook has ten ready-to-paste recipes for common shapes.

The bundled deploy pipeline

Every scaffolded repo ships its own .github/workflows/deploy.yml, two channels from one workflow:

• Push to main → the release channel: an immutable /<repo>/v<version>/ plus a mutable /<repo>/latest/ (and the same build at the repo's Pages root). Re-pushing main without bumping package.json's version is a no-op — it only rebuilds when a new v<version> doesn't exist yet.
• Push to dev → the dev channel: a mutable /<repo>/dev/, for live review inside Grist as you iterate.

If you scaffolded via "Use this template" with Include all branches checked, GitHub Pages is already pointed at the copied gh-pages branch — nothing else to configure. Scaffolding a fresh, non-template repo yourself needs two one-time steps instead:

1. Settings → Pages → Source: Deploy from a branch → gh-pages → / (the workflow creates the gh-pages branch itself, but Pages has to be pointed at it once — left on main, you'd see a blank page with a 404 for /src/main.tsx even though the workflow reports success).
2. Settings → Actions → General → Workflow permissions → Read and write permissions.

Hand-rolled (no template)

If you want the bare minimum instead of the CLI:

mkdir my-widget && cd my-widget
pnpm init
pnpm add react react-dom grist-widget-sdk
pnpm add -D typescript @types/react @types/react-dom vite @vitejs/plugin-react

Then create index.html (with the plugin-api script tag), src/main.tsx (React root), and src/App.tsx (your widget) — see the Cheat sheet for the smallest possible code, or the Cookbook for ten ready-to-paste recipes. The template path saves about ten minutes of boilerplate and one or two configuration gotchas, but the SDK works fine without it.