grist-widget-sdk docs

Appearance

Grist Plugin API Notes ​

Use this guide when touching Grist runtime integration in packages/core.

Purpose ​

grist-plugin-api is the host bridge between a widget iframe and a Grist document.

In this repository, widget-facing code should primarily consume the abstractions in @grist-widget-sdk/core instead of calling the global directly in app code.

Runtime requirements ​

  • Grist communication depends on the runtime script:
    • https://docs.getgrist.com/grist-plugin-api.js
  • Outside Grist (local dev/tests), the host runtime may be absent.
  • Hooks and providers must fail safely when runtime is unavailable.
  • Prefer useGrist() as the main integration surface.
  • Use GristWidgetProvider + GristBoundary for app-level setup.
  • Use useGristSchema() for schema/sample extraction needs.
  • Keep direct global integration encapsulated in SDK internals.

Common pitfalls ​

  • Calling Grist APIs before widget readiness is established.
  • Assuming selected record/table always exists.
  • Forgetting to handle empty/new-row states.
  • Writing direct global calls in app code where SDK helpers exist.

Change safety rules for agents ​

  • If adding new SDK behavior, expose it through public exports (not private paths).
  • If behavior changes affect consumers, update packages/core/README.md and apps/docs/files/.
  • Keep runtime assumptions explicit in types and docs.