Разработка кастомного плагина Strapi

Разработка плагинов для Strapi

Плагин Strapi — самодостаточный модуль с собственными content types, контроллерами, сервисами, маршрутами и UI-компонентами для admin panel. Официальные плагины (users-permissions, upload, email, i18n) построены по той же схеме. Кастомный плагин — способ упаковать переиспользуемую функциональность.

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

src/plugins/my-plugin/
├── admin/
│   └── src/
│       ├── index.tsx          # Регистрация в admin panel
│       ├── pages/
│       │   └── HomePage/
│       │       └── index.tsx
│       └── components/
├── server/
│   ├── index.ts               # Регистрация сервера
│   ├── content-types/         # Content types плагина
│   │   └── log-entry/
│   │       └── schema.json
│   ├── controllers/
│   │   └── my-controller.ts
│   ├── services/
│   │   └── my-service.ts
│   ├── routes/
│   │   └── my-routes.ts
│   └── middlewares/
├── package.json
└── strapi-server.js           # Точка входа для Strapi

Создание плагина через CLI

# В корне Strapi проекта
npx @strapi/sdk-plugin@latest generate
# Ввести: имя плагина, путь, язык (TypeScript)

Серверная часть (server/index.ts)

// server/index.ts
import controllers from './controllers'
import services from './services'
import routes from './routes'
import contentTypes from './content-types'

export default {
  register({ strapi }) {
    // Регистрация при старте
    strapi.customFields.register({
      name: 'color',
      plugin: 'my-plugin',
      type: 'string',
    })
  },

  bootstrap({ strapi }) {
    // Выполняется после старта Strapi
    strapi.log.info('My Plugin bootstrapped')
  },

  contentTypes,
  controllers,
  services,
  routes,
}

Сервис плагина

// server/services/analytics.ts
export default ({ strapi }) => ({
  async getTopContent(options: { collection: string; limit: number; period: 'day' | 'week' | 'month' }) {
    const { collection, limit, period } = options

    const periodMs = { day: 86400000, week: 604800000, month: 2592000000 }[period]
    const since = new Date(Date.now() - periodMs).toISOString()

    // Получить записи с количеством просмотров
    const items = await strapi.entityService.findMany(`api::${collection}.${collection}`, {
      filters: { updatedAt: { $gte: since } },
      sort: { viewCount: 'desc' },
      limit,
    })

    return items
  },

  async recordView(collection: string, docId: number, userId?: number) {
    await strapi.entityService.create('plugin::my-plugin.view-log', {
      data: {
        collection,
        docId: String(docId),
        userId: userId || null,
        ip: null,
        timestamp: new Date().toISOString(),
      },
    })

    // Обновить счётчик
    const doc = await strapi.entityService.findOne(`api::${collection}.${collection}`, docId)
    if (doc) {
      await strapi.entityService.update(`api::${collection}.${collection}`, docId, {
        data: { viewCount: ((doc as any).viewCount || 0) + 1 },
      })
    }
  },
})

Контроллер плагина

// server/controllers/analytics.ts
export default {
  async getStats(ctx) {
    const { collection = 'article', period = 'week', limit = 10 } = ctx.query

    const stats = await strapi
      .plugin('my-plugin')
      .service('analytics')
      .getTopContent({ collection, period, limit: Number(limit) })

    ctx.body = { data: stats }
  },

  async recordView(ctx) {
    const { collection, id } = ctx.params

    await strapi
      .plugin('my-plugin')
      .service('analytics')
      .recordView(collection, Number(id), ctx.state.user?.id)

    ctx.body = { success: true }
  },
}

Маршруты плагина

// server/routes/index.ts
export default [
  {
    method: 'GET',
    path: '/analytics/stats',
    handler: 'analytics.getStats',
    config: {
      policies: ['admin::isAuthenticatedAdmin'],
    },
  },
  {
    method: 'POST',
    path: '/analytics/:collection/:id/view',
    handler: 'analytics.recordView',
    config: {
      auth: false,
      middlewares: ['plugin::my-plugin.rate-limit'],
    },
  },
]

Admin UI компонент

// admin/src/index.tsx
import { prefixPluginTranslations } from '@strapi/helper-plugin'
import pluginId from './pluginId'
import HomePage from './pages/HomePage'
import { PluginIcon } from './components/PluginIcon'

export default {
  register(app: any) {
    app.addMenuLink({
      to: `/plugins/${pluginId}`,
      icon: PluginIcon,
      intlLabel: { id: `${pluginId}.plugin.name`, defaultMessage: 'Analytics' },
      Component: async () => {
        const { default: component } = await import('./pages/HomePage')
        return component
      },
    })

    app.registerPlugin({
      id: pluginId,
      name: 'My Analytics Plugin',
    })
  },

  bootstrap(app: any) {
    // Добавить панель к edit view конкретного content type
    app.injectContentManagerComponent('editView', 'right-links', {
      name: 'ViewCountWidget',
      Component: async () => {
        const { ViewCountWidget } = await import('./components/ViewCountWidget')
        return ViewCountWidget
      },
    })
  },
}

// admin/src/pages/HomePage/index.tsx
import { useEffect, useState } from 'react'
import { getFetchClient } from '@strapi/helper-plugin'

const pluginId = 'my-plugin'

const HomePage = () => {
  const [stats, setStats] = useState<any[]>([])
  const { get } = getFetchClient()

  useEffect(() => {
    get(`/${pluginId}/analytics/stats?period=week&limit=10`)
      .then(res => setStats(res.data.data))
  }, [])

  return (
    <div>
      <h1>Analytics Dashboard</h1>
      <table>
        <thead>
          <tr><th>Title</th><th>Views</th></tr>
        </thead>
        <tbody>
          {stats.map((item, i) => (
            <tr key={i}>
              <td>{item.title}</td>
              <td>{item.viewCount}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  )
}

export default HomePage

Конфигурация плагина

// config/plugins.js
module.exports = {
  'my-plugin': {
    enabled: true,
    config: {
      trackingEnabled: true,
      excludeAdminViews: true,
    },
  },
}

// Доступ к конфигурации в плагине
const config = strapi.config.get('plugin.my-plugin')

Публикация

// package.json плагина
{
  "name": "strapi-plugin-my-analytics",
  "version": "1.0.0",
  "strapi": {
    "kind": "plugin",
    "name": "my-plugin",
    "displayName": "My Analytics"
  },
  "peerDependencies": {
    "@strapi/strapi": ">=4.0.0"
  }
}

Сроки

Разработка полноценного плагина с сервером, контент-типом и admin UI — 5–8 дней.