Plate Plugins
Build Plate plugins that do not need a later plate-next cleanup.
This skill owns plugin authoring mechanics: semantic layer, durable source
owners, file topology, contextual typing, initial state, scoped stores/APIs and
transactions, React families, and package-local proof. The plugin law it
applies lives in docs/vision/plate.md (Plugin and component doctrine) and
docs/vision/plite.md (Plite API Direction); read the relevant section
instead of a copy here.
Required Reads
Before authoring or refactoring a plugin, read:
- creation-flow.md for semantic and file ownership;
- typing.md for inference and public contracts.
Use plugin-authoring-audit.md only
for current repo examples. Plate foundation builders and type tests outrank precedent.
Semantic Layer
Semantic base first, Plate second.
- If behavior matters without React, author it in
src/lib with
definePlugin.
- Lift an existing semantic base with
toReactPlugin only in its live React
adapter; do not re-author it with definePlugin.
- Use
definePlugin directly only for a real React/Plate-native plugin.
- Keep a plugin base-only when no React layer has an independent job.
Named direct-Plate exceptions:
- React render descriptors with no useful semantic base;
- DOM/editor-surface plugins with no useful semantic base;
- React node-prop or component behavior that has no non-React meaning.
Owner-First Topology
Colocation is the default.
- Put behavior with exactly one production owner inline in that plugin's
define*Plugin / .extend() chain. This includes one-use with*,
decorate*, normalizers, parsers, commands, corrections, matchers, state,
APIs, and tx callbacks.
For copied app/registry source, stop here and follow plate-ui; this skill does
not own copied-item colocation, dependency metadata, or browser proof.
Read this reference when authoring inferred plugin capabilities, current-owner context, API/transaction methods, component bindings, or Plite primitives.
React And Test Ownership
plate-ui owns component, hook, context, provider, primitive, and React 19
shape. This skill only implements that accepted shape inside the package and
proves package behavior.
- React tests live beside the component family or its single semantic
controller owner.
verify's testing reference
owns spec families, fixtures and inline test construction.
Read this reference before creating a public entrypoint, changing platejs
dependencies or peers, or moving a package into a platejs/<feature>
entrypoint. It holds the package host law, entrypoint creation and the Oxlint
boundary graph.
Read this reference when one feature must reach registry consumers across its
package, React adapter, copied UI, docs and release. The Plan playbook copies
the template into the plan, appends
Benchmark's performance-observability pack when the Scale proof row is yes,
and the Build playbook closes it with
node tooling/scripts/check-plate-feature.mjs <plan>.
- Headless and registry-only flows are first-class modes, not incomplete full
flows. Skip a manifest row only as
no with a concrete N/A reason.
Workflow
- Read the two required rule files.
- Decide the semantic layer and durable production, React-family, and test
owners before creating files.
- Search current Plate foundation builders/type tests and the closest clean package
analog. Do not copy a stale file graph. A plugin that wraps a native Plite
factory, as
HistoryPlugin and YjsPlugin do, copies every registration of
its closest wrapped analog, found by grepping that analog's name across
tooling/ and the lint configuration.
- Route reusable public forks to
best-api; otherwise keep the inferred
plugin chain inline.
- Define initial state, scoped store/API/update methods, relationships, flat
Plite-native fields, and React behavior in their durable owners.
- Delete superseded helper/component/hook/spec files and regenerate barrels.
- Prove the smallest honest surface:
- package typecheck and behavior tests;
- Plate foundation type tests when builder/public inference changes;
- compile/runtime proof that a required dependent sees staged capabilities;
- compile/runtime proof for staged tx-to-tx reuse when one tx stage consumes
another;
- runtime proof when a native runtime callback consumes a staged API;
- an active-transaction test when a query crosses a state-view boundary;
- React tests when React behavior changes;
pnpm --filter platejs build when a plugin wraps a native factory,
because the declaration build reports TS4094 errors the typecheck skips;
- Audit for stale helper names, root option helpers, nested updates, explicit
plugin annotations, empty config aliases, top-level plugin
config,
parameter-threaded editor / api / read / tx helpers, and one-use
file taxonomies.
References
1---2description: Use before adding or changing a plugin's stage fields or options, such as read middleware, contributions, transfer vetoes or landing policy, and for a feature that spans Plite, Plate, the registry and docs. Load it before any edit to a Base plugin file under packages/platejs/src, such as packages/platejs/src/features/*/lib/Base*Plugin.ts, even when the task reads as Plite core, editor behavior or a bug fix. Builds Plate plugins and entrypoints with semantic ownership, inference, scoped capabilities and package proof, and delivers a feature across its package, UI, docs and release. Use it also when a change touches a plugin's Markdown or HTML encode or decode mapping or its preserve claims.3name: plate-plugins4metadata:5 skiller:6 source: https://skillmd.com/skills/udecode/plate-plugins7 upstream: .agents/rules/plate-plugins.mdc8---910# Plate Plugins1112Build Plate plugins that do not need a later `plate-next` cleanup.1314This skill owns plugin authoring mechanics: semantic layer, durable source15owners, file topology, contextual typing, initial state, scoped stores/APIs and16transactions, React families, and package-local proof. The plugin law it17applies lives in `docs/vision/plate.md` (Plugin and component doctrine) and18`docs/vision/plite.md` (Plite API Direction); read the relevant section19instead of a copy here.2021## Required Reads2223Before authoring or refactoring a plugin, read:24251. [creation-flow.md](./rules/creation-flow.md) for semantic and file ownership;262. [typing.md](./rules/typing.md) for inference and public contracts.2728Use [plugin-authoring-audit.md](./references/plugin-authoring-audit.md) only29for current repo examples. Plate foundation builders and type tests outrank precedent.3031## Semantic Layer3233**Semantic base first, Plate second.**3435- If behavior matters without React, author it in `src/lib` with36 `definePlugin`.37- Lift an existing semantic base with `toReactPlugin` only in its live React38 adapter; do not re-author it with `definePlugin`.39- Use `definePlugin` directly only for a real React/Plate-native plugin.40- Keep a plugin base-only when no React layer has an independent job.4142Named direct-Plate exceptions:43441. React render descriptors with no useful semantic base;452. DOM/editor-surface plugins with no useful semantic base;463. React node-prop or component behavior that has no non-React meaning.4748## Owner-First Topology4950Colocation is the default.5152- Put behavior with exactly one production owner inline in that plugin's53 `define*Plugin` / `.extend()` chain. This includes one-use `with*`,54 `decorate*`, normalizers, parsers, commands, corrections, matchers, state,55 APIs, and tx callbacks.5657For copied app/registry source, stop here and follow `plate-ui`; this skill does58not own copied-item colocation, dependency metadata, or browser proof.5960## Capabilities And Inference → [capabilities.md](./rules/capabilities.md)6162Read this reference when authoring inferred plugin capabilities, current-owner context, API/transaction methods, component bindings, or Plite primitives.6364## React And Test Ownership6566- `plate-ui` owns component, hook, context, provider, primitive, and React 1967 shape. This skill only implements that accepted shape inside the package and68 proves package behavior.69- React tests live beside the component family or its single semantic70 controller owner. `verify`'s [testing reference](../verify/references/testing.md)71 owns spec families, fixtures and inline test construction.7273## Package Host → [package-host.md](./references/package-host.md)7475Read this reference before creating a public entrypoint, changing `platejs`76dependencies or peers, or moving a package into a `platejs/<feature>`77entrypoint. It holds the package host law, entrypoint creation and the Oxlint78boundary graph.7980## Feature Delivery → [manifest.md](./references/feature/manifest.md)8182Read this reference when one feature must reach registry consumers across its83package, React adapter, copied UI, docs and release. The Plan playbook copies84the [template](./references/feature/template.md) into the plan, appends85Benchmark's performance-observability pack when the Scale proof row is `yes`,86and the Build playbook closes it with87`node tooling/scripts/check-plate-feature.mjs <plan>`.8889- Headless and registry-only flows are first-class modes, not incomplete full90 flows. Skip a manifest row only as `no` with a concrete N/A reason.9192## Workflow93941. Read the two required rule files.952. Decide the semantic layer and durable production, React-family, and test96 owners before creating files.973. Search current Plate foundation builders/type tests and the closest clean package98 analog. Do not copy a stale file graph. A plugin that wraps a native Plite99 factory, as `HistoryPlugin` and `YjsPlugin` do, copies every registration of100 its closest wrapped analog, found by grepping that analog's name across101 `tooling/` and the lint configuration.1024. Route reusable public forks to `best-api`; otherwise keep the inferred103 plugin chain inline.1045. Define initial state, scoped store/API/update methods, relationships, flat105 Plite-native fields, and React behavior in their durable owners.1066. Delete superseded helper/component/hook/spec files and regenerate barrels.1077. Prove the smallest honest surface:108 - package typecheck and behavior tests;109 - Plate foundation type tests when builder/public inference changes;110 - compile/runtime proof that a required dependent sees staged capabilities;111 - compile/runtime proof for staged tx-to-tx reuse when one tx stage consumes112 another;113 - runtime proof when a native runtime callback consumes a staged API;114 - an active-transaction test when a query crosses a state-view boundary;115 - React tests when React behavior changes;116 - `pnpm --filter platejs build` when a plugin wraps a native factory,117 because the declaration build reports TS4094 errors the typecheck skips;1188. Audit for stale helper names, root option helpers, nested updates, explicit119 plugin annotations, empty config aliases, top-level plugin `config`,120 parameter-threaded `editor` / `api` / `read` / `tx` helpers, and one-use121 file taxonomies.122123## References124125- [creation-flow.md](./rules/creation-flow.md) — semantic and file ownership126- [typing.md](./rules/typing.md) — contextual inference and contracts127- [plugin-authoring-audit.md](./references/plugin-authoring-audit.md) — current128 examples and rejected precedent129- [package-host.md](./references/package-host.md) — package host law, entrypoint130 creation and the import graph131- [manifest.md](./references/feature/manifest.md) — the Feature Manifest,132 package boundary contract and flow modes, with its plan133 [template](./references/feature/template.md)