OpenParable
Skip to content
← Back to skills

Sanity Default Plugins

Development
sanity-default-plugins

Sanity Default Plugins is an Agent Skill for development published in the sanity-io/sanity repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create and wire Sanity core plugins using the monorepo's default plugin conventions. Use when adding, modifying, or reviewing plugins under packages/sanity/src/core, especially plugins added through resolveDefaultPlugins or studio.components middleware.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/sanity-io/sanity/blob/HEAD/.agents/skills/sanity-default-plugins/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sanity-default-plugins, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Sanity Core Plugin

Start Here

Before adding a core plugin, read the sanity-plugin-authoring skill at ../sanity-plugin-authoring/SKILL.md to understand the general Sanity plugin API and what plugins can provide. Then inspect nearby plugins and these files:

  • packages/sanity/src/core/config/resolveDefaultPlugins.ts
  • packages/sanity/src/core/config/types.ts
  • packages/sanity/src/core/config/studio/types.ts
  • A similar plugin under packages/sanity/src/core/*/plugin/

The new plugin should be added inside core so it can be imported into the default plugins.

Prefer local patterns over new abstractions.

Plugin Shape

Use definePlugin and export a stable internal name constant:

import {definePlugin} from '../../config/definePlugin'

export const FEATURE_NAME = 'sanity/feature'

export const feature = definePlugin({
  name: FEATURE_NAME,
  studio: {
    components: {
      layout: FeatureStudioLayout,
    },
  },
  i18n: {
    bundles: [featureUsEnglishLocaleBundle],
  },
})

Use ../../config/definePlugin when matching existing internal plugin files. ../../config is also available in some folders.

Locale Resources

Default core plugins that render UI text should add a locale resource bundle. Follow the pattern from packages/sanity/src/core/singleDocRelease:

  • packages/sanity/src/core/<feature>/i18n/index.ts: exports the locale namespace, US English bundle, and resource key type.
  • packages/sanity/src/core/<feature>/i18n/resources.ts: exports default locale strings and keyof resource type.
  • packages/sanity/src/core/<feature>/plugin/index.ts: imports the bundle and registers it under i18n.bundles.

Example i18n/index.ts:

import {type LocaleResourceBundle} from '../../i18n'

export const featureNamespace: 'feature' = 'feature'

export const featureUsEnglishLocaleBundle: LocaleResourceBundle = {
  locale: 'en-US',
  namespace: featureNamespace,
  resources: () => import('./resources'),
}

export type {FeatureLocaleResourceKeys} from './resources'

Example i18n/resources.ts:

const featureLocaleStrings = {
  'action.example': 'Example',
}

export type FeatureLocaleResourceKeys = keyof typeof featureLocaleStrings

export default featureLocaleStrings

Example plugin registration:

import {featureUsEnglishLocaleBundle} from '../i18n'

export const feature = definePlugin({
  name: FEATURE_NAME,
  i18n: {
    bundles: [featureUsEnglishLocaleBundle],
  },
})

Default Plugin Wiring

Default core plugins are listed in resolveDefaultPlugins.ts.

  1. Import the plugin and its name constant.
  2. Add the plugin to defaultPlugins(options) in the desired composition order.
  3. If gated, add a plugin.name === FEATURE_NAME branch in getDefaultPlugins.
  4. Add any required options to DefaultPluginsWorkspaceOptions in types.ts.
  5. In getDefaultPluginsOptions, build default plugin options directly from workspace config defaults and spreads. Do not call config property reducers here; reducers belong to resolved source/workspace config, while default plugin options are a lightweight workspace-level input for plugin insertion.
  6. Update packages/sanity/src/core/config/__tests__/resolveConfig.test.ts with focused default plugin tests:
    • The plugin is not added by default.
    • The plugin is added when the proper config flag is enabled.
  7. Add ordering coverage when plugin order affects UI composition.

Example default option shape:

variants: {
  enabled: false,
  ...workspace.beta?.variants,
}

Remember: user plugins are appended before default plugins in prepareConfig.tsx, then the component middleware chain reverses flattened config order. Check the existing chain before relying on wrapper order.

Verification

For default plugin changes, run:

pnpm vitest run --project=sanity packages/sanity/src/core/config/__tests__/resolveConfig.test.ts

Also run lint/read diagnostics for edited files. Add component-level tests only when the plugin changes runtime rendering beyond insertion.