Templates

Scaffolds you can paste into a fresh directory with degit (no npx create-grist-widget yet — the CLI is on the roadmap, the template approach is the stable answer for now).

Vite (current)

The canonical scaffold. React 19 + TypeScript + Tailwind + a working provider chain.

npx degit ArthurBlanchon/grist-widget-sdk/templates/grist-widget-template-vite my-widget
cd my-widget
pnpm install
pnpm dev

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.

HTML and Next.js (planned)

Two more templates are queued behind the Vite scaffold:

• HTML. A single-file template with no build step — index.html
  • the SDK loaded via <script type="module"> from a CDN. Useful for tiny one-off widgets that should not require a Node toolchain.
• Next.js. App-router scaffold with next/script for the plugin api and a single app/page.tsx widget. Useful when the widget is part of a larger product that already lives in Next.js.

The repo will not ship these until they have the same level of polish as the Vite template — see the open issue for status.

Hand-rolled (no template)

If you want the bare minimum:

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 Getting started "Hello world" section for the smallest possible code.

The template path saves about ten minutes of boilerplate and one or two configuration gotchas — but the SDK works fine without it.