Architecture

Overview

This repository uses pnpm workspaces and Turborepo to coordinate multiple packages:

• packages/core: published SDK package (@grist-widget-sdk/core)
• apps/widgets: local examples/playground app
• apps/docs: VitePress docs site
• templates/grist-widget-template-vite: starter project template

Package boundaries

packages/core

• Library package built with tsup (not a Vite app)
• Primary entrypoint: @grist-widget-sdk/core
• Testing subpath: @grist-widget-sdk/core/testing
• Public exports are re-exported from packages/core/src/hooks/index.ts

apps/widgets

• React + Vite app used to try and showcase SDK usage
• Depends on @grist-widget-sdk/core through workspace:^
• Uses app-level UI/tooling (Tailwind, shadcn, router) that should not be moved into packages/core

apps/docs

• VitePress documentation workspace
• Hosts AI-agent-facing operational docs under apps/docs/files/

templates/grist-widget-template-vite

• Standalone Vite starter
• Also depends on @grist-widget-sdk/core with workspace:^ while inside this monorepo
• Should stay isolated enough to be used as a scaffolded external project

Runtime model

Widget runtime flow:

Grist host document
  -> iframe widget app
    -> grist-plugin-api global
      -> @grist-widget-sdk/core hooks/providers
        -> widget React components

Build orchestration

turbo.json defines:

• build depends on upstream workspace builds via dependsOn: ["^build"]
• dev tasks are persistent and uncached
• test depends on upstream build

In practice, building apps that consume packages/core first builds the SDK package.