plugin-transfer

Plugin Transfer

Use this skill when migrating an existing plugin repository into sanity-io/plugins.

Start Here

Always start with:

pnpm generate "copy plugin"

This is the canonical transfer flow and scaffolds monorepo-compatible files and test-studio wiring.

Do not keep migration TODOs in the repo. If the generator creates README.todo.md, delete it after moving its contents into the transfer PR description. Maintainers can update PR checklists directly on GitHub without a code change.

Required vs Unnecessary Config

Keep and maintain these monorepo config files in the transferred plugin:

• package.json
• tsdown.config.ts
• tsconfig.json
• vitest.config.ts

Do not copy standalone-repo-only setup such as custom root CI/build/lint/test configs that are already handled by this monorepo.

Clean Up the Transferred README

The original README.md is preserved, but old standalone-repo content is almost always stale in the monorepo. Remove or rewrite the following before opening the PR:

• Old release/development sections. Delete sections that describe the original repo's release or dev tooling, e.g. ## Develop & test (typically references @sanity/plugin-kit) and ### Release new version (references the original repo's GitHub Actions / semantic-release). The monorepo handles building, testing, and releasing centrally, so these instructions are wrong here.
• Links to old/forked versions. Remove pointers like "for the v2 version, see this other repo" that link to pre-transfer forks or legacy repositories.
• Specific Sanity Studio major versions. Do not reference the current latest Studio major (e.g. "Sanity Studio v6") since it ages quickly, and do not mention long-gone majors like v3. Reword phrasing such as "migrated to Sanity Studio V3" / "only the v3 version is maintained" to a version-agnostic statement (e.g. "maintained by Sanity.io"). Only mention a version when genuinely necessary—at most as v2 - legacy to disambiguate a legacy line—and usually omit it entirely.

Keep the substance that is still accurate: intro/description, screenshots, acknowledgements, install, usage, configuration, and license sections.

Required Transfer Checks

1. Keep the original plugin README.md in the new plugin workspace, but clean it up (see Clean Up the Transferred README).
2. Restore LICENSE from the original repository when it credits authors beyond Sanity.io alone (the copy-plugin generator deletes it during cleanup). If kept, update the copyright year(s) to the current year.
3. Add and verify the generated test-studio example under dev/test-studio/src/<plugin-example>/index.tsx.
4. Confirm the plugin is wired in dev/test-studio/sanity.config.ts.
5. Do not update .github/CODEOWNERS during transfer unless explicitly requested.
6. Add a changeset with a major bump for the transferred plugin (see Changesets).
7. Update the root README.md plugins table with the transferred plugin.
8. Add pending transfer TODOs to the transfer PR description only (see PR description checklist—not in a README or other repo file).
9. Run the full pre-PR verification suite (see Before Submitting a PR).

Before Submitting a PR

Run these commands in order. All must pass or CI will fail:

# 1. Format code
pnpm format

# 2. Check for unused exports, dependencies, and catalog entries
pnpm knip

# 3. Run linters (includes TypeScript type checking)
pnpm lint

# 4. Build all packages
pnpm build

# 5. Run tests
pnpm test run

Knip

The copy-plugin generator adds a workspace entry to knip.jsonc. After transfer, fix any knip issues in the plugin:

• Remove unused exports (e.g. helpers only used internally should not be exported).
• Remove dead code flagged as unused.

Catalog warnings for dev/* workspaces (e.g. @sanity/vision used only by dev/test-studio) are expected—the root knip.jsonc sets "catalog": "warn" for those.

Lint

Transferred plugins may carry legacy patterns that fail monorepo lint rules. Fix what you can; for remaining issues in legacy src/ or test/ code, add targeted .oxlintrc.json overrides or ignorePatterns rather than disabling rules repo-wide.

Common legacy fixes:

• Replace createRequire / require() with ESM import (add "resolveJsonModule": true to the plugin tsconfig.json for JSON imports).
• Use import.meta.url with fileURLToPath instead of __dirname in tests.
• Remove stale eslint-disable comments that oxlint reports as unused.

Duplicate sanity peer variants break type-aware lint

Type-aware lint can fail (sometimes intermittently, especially on cold installs) with errors like Type 'import(".../.pnpm/sanity@X_<hashA>/...").D' is not assignable to type 'import(".../.pnpm/sanity@X_<hashB>/...").D' in dev/test-studio/src/** examples. This happens when the transferred plugin resolves sanity to a different pnpm peer-variant than the other plugins, creating an extra duplicate copy of sanity's type definitions.

To keep the plugin on the shared sanity variant, declare these in the plugin devDependencies:

• "@types/node": "catalog:"
• "styled-components": "catalog:" (when the plugin depends on @sanity/ui, which peers on styled-components; without the declaration pnpm may auto-install a separate copy of the peer)

Verify alignment by checking that the plugin importer's sanity version string in pnpm-lock.yaml matches other plugins (e.g. plugins/@sanity/sfcc).

Do not migrate styling during a transfer. When the plugin already uses styled-components, leave it in place for the initial port — the goal is a faithful, low-risk move. styled-components is still migrated to vanilla-extract (the styling target for every plugin), but in a separate follow-up PR, done with care to preserve visual fidelity and avoid regressions. The styled-components: catalog: alignment above applies until then. See the sanity-plugin-best-practices styling reference (Migrating off styled-components).

Tests

Vitest runs against built dist/ output (pretest builds packages automatically). Fix path resolution and module import issues in legacy test files. The plugin's own test/ suite (if present) runs via the root vitest config when included in the plugin workspace.

Changesets

Every transferred plugin needs a major changeset. Compare the transferred plugin's package.json (peer dependencies, engines, exports, and build config) against the last published version on npm. Do not copy a template blindly—only list breaking changes that actually apply.

Credit every contributor

Because the transfer PR is opened by someone else (often the 🤖 bot), the generated release would otherwise thank the wrong person. Add an author: directive so the changelog credits the people who actually built the plugin. Multiple author: lines are supported, so list everyone who worked on the plugin being ported — not just the latest author — so they all get their thanks in the release notes.

• Use the contributors' GitHub usernames, always with a leading @ (e.g. author: @stipsan).
• Put each author: line on its own line, before the summary text. The lines are stripped from the rendered changelog.
• Gather contributors from the original repo's commit history, package.json author/contributors, and the README acknowledgements.

---
'package-name': major
---

author: @stipsan
author: @rexxars

Port PACKAGE-NAME to the Sanity plugins monorepo

This produces a release line thanking each contributor:

Thanks @stipsan, @rexxars! - Port PACKAGE-NAME to the Sanity plugins monorepo

See AGENTS.md → Crediting Original Authors for the full rationale.

Format

Use this format (add the author: lines from Credit every contributor above the summary):

---
'package-name': major
---

author: @stipsan
author: @rexxars

Port PACKAGE-NAME to the Sanity plugins monorepo

This major release includes several breaking changes as part of the migration to the monorepo:

- **React Compiler enabled**: ...
- **ESM-only**: CommonJS support has been removed. The package now ships only ESM
- **React 19.2+ required**: ...
- **Sanity Studio v5+ required**: ...
- **Node.js 20.19+ required**: ...

Include additional bullets only when they apply to the plugin—for example:

• styled-components 6.1+ required (UI plugins that use styled-components)
• react-dom 19.2+ required (when newly added as a peer dependency)
• Dropped Sanity v3/v4 support (when the previous peer range allowed older Studio versions)

Example for sanity-naive-html-serializer:

---
'sanity-naive-html-serializer': major
---

author: @stipsan
author: @rexxars

Port sanity-naive-html-serializer to the Sanity plugins monorepo

This major release includes several breaking changes as part of the migration to the monorepo:

- **React Compiler enabled**: The package is now built with React Compiler targeting React 19
- **ESM-only**: CommonJS support has been removed. The package now ships only ESM
- **React 19.2+ required**: Minimum React version is now 19.2 (previously ^18.3 || ^19)
- **react-dom 19.2+ required**: `react-dom` is now a required peer dependency
- **Sanity Studio v5+ required**: Minimum Sanity version is now v5 (Sanity v3 and v4 are no longer supported)
- **Node.js 20.19+ required**: Minimum Node.js version is now 20.19 (previously >=18)

PR description checklist

Put all pending transfer work in the PR description as unchecked checkboxes. Do not create README.todo.md or similar todo files in the plugin workspace—the maintainer should be able to check items off on GitHub without opening a PR to edit repo files.

Include these sections in every transfer PR:

Transfer verification

• Trusted publishing configured: npm trust github <package-name> --file=release.yml --repository=sanity-io/plugins
• package.json dependencies/peerDependencies/exports verified against original repo
• LICENSE restored with updated copyright year when the original credits authors beyond Sanity.io alone
• Test studio example wired and manually verified (pnpm dev)
• pnpm format, pnpm knip, pnpm lint, pnpm build, pnpm test run all pass
• Major changeset added with validated breaking changes

Maintainer follow-up

Agents cannot complete these steps themselves. Ask the maintainer to handle them:

• Update the original repo README (<link to readme>) and replace it with: # [This plugin has moved](<new location>)
• Transfer pending issues from the original repo to this monorepo and label them as <plugin-name>
• Archive the original repo: <repo link>/settings

Example for sanity-naive-html-serializer:

• Update the original repo README (https://github.com/sanity-io/sanity-naive-html-serializer/blob/main/README.md) and replace it with: # [This plugin has moved](https://github.com/sanity-io/plugins/tree/main/plugins/sanity-naive-html-serializer)
• Transfer pending issues from the original repo to this monorepo and label them as naive-html-serializer
• Archive the original repo: https://github.com/sanity-io/sanity-naive-html-serializer/settings

Anything Else To Consider

• Do not migrate styling during the transfer. Keep an existing styled-components plugin on styled-components for the initial port; defer any vanilla-extract migration to a follow-up PR (see the styling note above).
• Review copied dependencies and peer dependencies carefully.
• Run the Before Submitting a PR verification suite—not just pnpm build and pnpm dev.
• Use pnpm dev to manually verify the test-studio example after the automated checks pass.