grist-widget-sdk docs

Appearance

Deploy Notes ​

Use this document when deployment behavior or CI build commands are involved.

Expected deploy targets ​

This repository is structured so that at minimum these artifacts are deployable:

  • docs site from apps/docs
  • widgets app from apps/playground
  • template app from templates/grist-widget-template-vite

Cloudflare Pages (3 projects) ​

Recommended setup is one Pages project per target:

  • docs project
  • widgets project
  • templates project

The safest default is:

  • set Root directory to repository root
  • use pnpm --filter ... commands with real workspace names
  • set Build output directory to a path relative to repository root

docs project ​

  • Build command:
bash
pnpm install --frozen-lockfile && pnpm build:docs
  • Build output directory:
text
apps/docs/.vitepress/dist

widgets project ​

Use this command even if widgets currently builds without importing core directly. It prevents future breakages once widgets starts using grist-widget-sdk.

  • Build command:
bash
pnpm install --frozen-lockfile && pnpm build:playground
  • Build output directory:
text
apps/playground/dist

templates project ​

Template code imports grist-widget-sdk, so core must be built first.

  • Build command:
bash
pnpm install --frozen-lockfile && pnpm --filter grist-widget-sdk build && pnpm --filter grist-widget-template-vite build
  • Build output directory:
text
templates/grist-widget-template-vite/dist

Common Cloudflare errors and fixes ​

  • No projects matched the filters: the --filter value does not match package.json:name.
  • Output directory ".../.../dist" not found: Root directory + output path are duplicated. If Root is already apps/playground, output should be dist (not apps/playground/dist).
  • Cannot find module 'grist-widget-sdk': build grist-widget-sdk first in the same command chain.
  • No Wrangler configuration file found and No functions dir at /functions found: expected for static Pages deployments.

Build commands (workspace-safe) ​

From repository root:

bash
pnpm build        # all workspaces except docs
pnpm build:docs   # VitePress only

Per workspace:

bash
pnpm build:docs
pnpm build:playground

Build ordering guarantees ​

turbo.json uses:

  • build.dependsOn: ["^build"]
  • test.dependsOn: ["^build"]

This ensures dependent apps build against freshly built upstream workspace packages such as grist-widget-sdk.

Static hosting notes ​

  • apps/playground/public/_redirects enables SPA fallback routing for static hosting.
  • apps/docs outputs static docs from VitePress to .vitepress/dist.

Agent checklist before touching deploy config ​

  • Confirm workspace/package names still match commands.
  • Confirm output paths used by hosting provider still match build output.
  • Confirm no deploy instructions reference removed directories.