Разработка кастомных плагинов Sanity Studio

Разработка кастомных плагинов Sanity Studio

Плагин Sanity Studio — npm-пакет, добавляющий в Studio новые инструменты (tools), поля, компоненты, действия. Плагин регистрируется в sanity.config.ts через массив plugins. Официальные плагины (@sanity/vision, @sanity/media, @sanity/dashboard) построены по той же схеме.

Структура плагина

sanity-plugin-my-tool/
├── src/
│   ├── index.ts          # definePlugin — точка входа
│   ├── components/
│   │   └── MyTool.tsx
│   ├── schema/
│   │   └── additionalType.ts
│   └── actions/
│       └── publishWithSlug.ts
├── package.json
└── tsconfig.json

definePlugin — основа

// src/index.ts
import { definePlugin } from 'sanity'
import { MyTool } from './components/MyTool'
import { additionalType } from './schema/additionalType'
import { publishWithSlugAction } from './actions/publishWithSlug'
import type { DocumentActionComponent } from 'sanity'

export interface MyPluginConfig {
  apiEndpoint?: string
  enableDashboard?: boolean
}

export const myPlugin = definePlugin<MyPluginConfig>((config = {}) => {
  const { apiEndpoint = '/api', enableDashboard = true } = config

  return {
    name: 'my-plugin',

    // Добавить дополнительные типы схем
    schema: {
      types: [additionalType],
    },

    // Добавить инструмент (вкладка в навигации)
    tools: enableDashboard
      ? [
          {
            name: 'my-dashboard',
            title: 'Dashboard',
            icon: () => '📊',
            component: MyTool,
          },
        ]
      : [],

    // Переопределить действия для документов
    document: {
      actions: (prev: DocumentActionComponent[], ctx: any) => {
        if (ctx.schemaType === 'post') {
          return [publishWithSlugAction, ...prev]
        }
        return prev
      },
    },
  }
})

Tool компонент (дополнительный экран Studio)

// src/components/MyTool.tsx
import { useState, useEffect } from 'react'
import { useClient } from 'sanity'

export function MyTool() {
  const client = useClient({ apiVersion: '2024-01-01' })
  const [stats, setStats] = useState<any>(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    async function fetchStats() {
      const [posts, drafts] = await Promise.all([
        client.fetch(`count(*[_type == "post" && !(_id in path("drafts.**"))])`),
        client.fetch(`count(*[_type == "post" && _id in path("drafts.**")])`),
      ])

      // SEO quality check
      const missingMeta = await client.fetch(`
        *[_type == "post" && (!defined(seoTitle) || !defined(seoDescription))] {
          _id, title, "slug": slug.current
        }
      `)

      setStats({ posts, drafts, missingMeta })
      setLoading(false)
    }
    fetchStats()
  }, [client])

  if (loading) return <div style={{ padding: 24 }}>Loading...</div>

  return (
    <div style={{ padding: 24 }}>
      <h2>Content Dashboard</h2>

      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 16, marginBottom: 24 }}>
        <StatCard label="Published posts" value={stats.posts} />
        <StatCard label="Drafts" value={stats.drafts} />
        <StatCard label="Missing SEO" value={stats.missingMeta.length} alert={stats.missingMeta.length > 0} />
      </div>

      {stats.missingMeta.length > 0 && (
        <div>
          <h3>Posts with missing SEO metadata</h3>
          <table style={{ width: '100%', borderCollapse: 'collapse' }}>
            <thead>
              <tr style={{ background: '#f5f5f5' }}>
                <th style={{ padding: '8px', textAlign: 'left' }}>Title</th>
                <th style={{ padding: '8px', textAlign: 'left' }}>Slug</th>
              </tr>
            </thead>
            <tbody>
              {stats.missingMeta.map((post: any) => (
                <tr key={post._id} style={{ borderTop: '1px solid #eee' }}>
                  <td style={{ padding: '8px' }}>{post.title}</td>
                  <td style={{ padding: '8px' }}>/posts/{post.slug}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}
    </div>
  )
}

const StatCard = ({ label, value, alert }: { label: string; value: number; alert?: boolean }) => (
  <div style={{
    padding: 16,
    border: `1px solid ${alert ? '#ff6b6b' : '#e0e0e0'}`,
    borderRadius: 8,
    background: alert ? '#fff5f5' : 'white',
  }}>
    <div style={{ fontSize: 32, fontWeight: 700, color: alert ? '#e53e3e' : 'inherit' }}>{value}</div>
    <div style={{ fontSize: 13, color: '#666' }}>{label}</div>
  </div>
)

Document Action (кастомное действие в форме)

// src/actions/publishWithSlug.ts
import { useDocumentOperation } from 'sanity'
import type { DocumentActionProps, DocumentActionComponent } from 'sanity'

export const publishWithSlugAction: DocumentActionComponent = (props: DocumentActionProps) => {
  const { patch, publish } = useDocumentOperation(props.id, props.type)
  const { draft } = props

  return {
    label: 'Publish',
    icon: () => '🚀',
    disabled: !draft || publish.disabled,
    onHandle: async () => {
      // Генерировать slug если отсутствует
      if (!draft?.slug?.current && draft?.title) {
        const slug = (draft.title as string)
          .toLowerCase()
          .replace(/\s+/g, '-')
          .replace(/[^\w-]/g, '')

        patch.execute([{ set: { slug: { _type: 'slug', current: slug } } }])
        // Подождать применения патча
        await new Promise(r => setTimeout(r, 100))
      }

      publish.execute()
      props.onComplete()
    },
  }
}

Document Badge (метка на документе)

// src/badges/seoStatus.ts
import type { DocumentBadgeComponent } from 'sanity'

export const seoBadge: DocumentBadgeComponent = props => {
  const { published } = props

  if (!published) return null

  const hasAllMeta =
    published.seoTitle &&
    published.seoDescription &&
    published.mainImage

  return hasAllMeta
    ? { label: 'SEO ✓', color: 'success' }
    : { label: 'SEO missing', color: 'warning' }
}

// Регистрация badge в sanity.config.ts
document: {
  badges: (prev, ctx) => {
    if (ctx.schemaType === 'post') {
      return [...prev, seoBadge]
    }
    return prev
  },
}

Публикация плагина как npm-пакета

// package.json
{
  "name": "sanity-plugin-content-dashboard",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "sanityExchangeUrl": "https://www.sanity.io/plugins/...",
  "keywords": ["sanity", "sanity-plugin"],
  "peerDependencies": {
    "sanity": "^3.0.0",
    "react": "^18.0.0"
  },
  "scripts": {
    "build": "plugin-kit verify-package && pkg-utils build",
    "watch": "pkg-utils watch"
  }
}

npm install @sanity/plugin-kit --save-dev
npx plugin-kit verify-package  # проверка перед публикацией
npm publish

Сроки

Разработка плагина с дашбордом, кастомными actions и badges — 4–6 дней.