DatoCMS Plugin

Workflow

1. Inspect silently:

   • package.json

     , package manager, scripts, plugin metadata, and installed SDK/UI versions
   • top-level

     connect()

     call, usually

     src/main.tsx

     or

     src/index.tsx

   • touched hook pair, render component, helper, CSS file, and current UI pattern
   • plugin-local

     AGENTS.md

     if present
2. Classify the request:
   • Existing plugin: package already exists and user asks to patch, add, maintain, fix, release-prep, or restyle. Default here.
   • New plugin: user asks to create/scaffold/bootstrap a plugin folder, or no plugin project exists.
   • Design pass: request mentions styling, layout, density, spacing, theme, dark mode, Canvas tokens, legacy CSS variables, hardcoded colors, forms, tables, panels, controls, or matching DatoCMS UI patterns.
   • Mixed: combine hook/scaffold work with design changes in one pass.
3. Ask only when inspection cannot resolve a behavior-changing choice:
   • plugin/folder name for a new scaffold
   • private vs marketplace plugin when package metadata changes
   • target model/field/surface when several are plausible
   • whether a new permission or dependency is allowed
   • whether direct browser CMA calls are required instead of SDK helpers
4. Load references after file inspection. Use the reference for the touched surface; do not load the full bundle.
5. Patch in place:
   • keep the existing file layout, package manager, scripts, naming, and UI structure
   • update paired hooks together: declaration + render, trigger + modal, dropdown declaration + execute handler
   • update permissions and package metadata in the same patch when the code path needs them
   • add dependencies only when the implementation imports them
6. Verify with the plugin's existing command. Prefer the build script; add typecheck, lint, or tests only when the project already defines them and they cover the change.
7. Report the patch, command result, and remaining DatoCMS check: config save, field render, modal resolve, asset select, permission branch, page navigation, or resize behavior.

Reference map

Common

references/rapid-patterns.md

references/connect-conventions.md

connect()

references/sdk-connect-and-frames.md

ctx

references/sdk-context-and-cma.md

references/current-plugin-patterns.md

references/permissions.md

references/form-values.md

New plugin

references/project-scaffold.md

references/surface-starters.md

Surfaces

references/config-screen.md

references/field-extensions.md

references/sidebar-panels.md

references/custom-pages.md

references/dropdown-actions.md

references/lifecycle-hooks.md

references/modals.md

references/outlets.md

references/inspectors.md

references/asset-sources.md

references/upload-sidebars.md

references/structured-text.md

references/record-presentation.md

Design

references/dark-mode-upgrade.md

references/design-foundations.md

references/design-datocms-react-ui-bridge.md

references/design-tokens.md

references/design-layouts.md

references/design-forms-and-controls.md

references/design-navigation-feedback-and-data-display.md

references/design-plugin-surfaces.md

references/design-raw-css-fallbacks.md

datocms-react-ui

Guardrails

• Keep exactly one top-level

  connect()

  call.
• Inspect existing

  connect()

  before adding hooks.
• Import

  datocms-react-ui/styles.css

  once in the plugin entry file.
• Wrap every rendered surface in

  <Canvas ctx={ctx}>

  .
• Use

  <Canvas ctx={ctx} noAutoResizer>

  for pages, inspectors, and full-width sidebars.
• Use

  switch

  for ID-dispatched render hooks.
• Use

  import type { ... }

  for SDK types.
• Guard

  ctx.item

  before reading saved-record data.
• Use

  get(ctx.formValues, ctx.fieldPath)

  in field extensions; use localized-value helpers elsewhere.
• Use deep-compare effects when depending on

  ctx

  object properties.
• Keep

  ctx.openModal()

  parameters and

  ctx.resolve()

  values JSON-serializable.
• Normalize stored plugin parameters at read/save boundaries.
• Use

  ctx.setParameters()

  directly in

  renderManualFieldExtensionConfigScreen

  .
• Do not create editor field extensions for modular content, single block, or Structured Text fields; use addon extensions instead.
• Prefer SDK helpers before browser CMA calls. If browser CMA is required, use

  @datocms/cma-client-browser

  , add only required permissions, and guard missing

  ctx.currentUserAccessToken

  .
• Keep modals, sidebars, and config screens compact.

Routing

• Standalone CMA scripts, schema imports, record operations, or migrations outside a plugin iframe ->

  datocms-cma

  or

  datocms-cli

  .
• Website preview, Content Link, draft mode, cache tags, frontend rendering, or framework setup ->

  datocms-frontend-integrations

  or

  datocms-setup

  .
• Content modeling decisions ->

  datocms-content-modeling

  .
• Content delivery GraphQL query work ->

  datocms-cda

  .