grist-widget-sdk docs

Appearance

grist-widget-sdk - AI Agent Guide ​

Start here before changing code. This file is the primary orientation document for AI agents working in this monorepo.

What this repository is ​

grist-widget-sdk is a pnpm monorepo for building Grist widgets with React and TypeScript.

It contains:

  • a reusable SDK package: @grist-widget-sdk/core
  • a widget examples app: apps/widgets
  • a Vite template for external users: templates/grist-widget-template-vite
  • this documentation site: apps/docs

Fast navigation ​

  • Read architecture and package boundaries: apps/docs/files/architecture.md
  • Read coding and safety conventions: apps/docs/files/conventions.md
  • Read testing strategy: apps/docs/files/testing-patterns.md
  • Read build/deploy behavior: apps/docs/files/deploy.md
  • Read core package build rules: apps/docs/files/vite-library-mode.md
  • Read Grist runtime integration notes: apps/docs/files/grist-plugin-api.md

Monorepo structure (current) ​

text
grist-widget-sdk/
  apps/
    docs/                         # VitePress documentation
    widgets/                      # React + Vite widgets playground
  packages/
    core/                         # @grist-widget-sdk/core library (tsup)
  templates/
    grist-widget-template-vite/   # standalone starter template

Source of truth by area ​

  • Public SDK API surface: packages/core/src/hooks/index.ts
  • SDK package exports: packages/core/package.json
  • SDK build config: packages/core/tsup.config.ts
  • Widget app scripts and dependencies: apps/widgets/package.json
  • Workspace orchestration: package.json, turbo.json, pnpm-workspace.yaml

Core commands ​

From repository root:

bash
pnpm install
pnpm dev
pnpm build
pnpm test

Target one workspace when needed:

bash
pnpm --filter @grist-widget-sdk/core dev
pnpm --filter @grist-widget-sdk/core build
pnpm --filter @grist-widget-sdk/core test
pnpm --filter grist-widget-examples dev
pnpm --filter docs docs:dev

Agent operating rules ​

  • Keep changes minimal and scoped to the user request.
  • Preserve package boundaries (do not leak app-only code into packages/core).
  • Do not introduce direct grist global usage in widget code when useGrist() covers the use case.
  • Prefer updating docs when behavior or API contracts change.
  • Run relevant checks after edits (build, test, or focused workspace scripts).

External references ​