Datocms Plugin

DatoCMS Plugin

Plugin development workflow. Patch existing plugins in place; scaffold only when no plugin exists or the user asks for a new project.

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

New plugin

Surfaces

Design

For design work, prefer public datocms-react-ui components when they match the required shape. Fall back to local React/CSS only when public components do not express the layout cleanly. Use Canvas tokens and variables directly; customize beyond them only for explicit product styling, vendor widgets, media treatments, data visualization, or effects they cannot express.

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.