К основному содержанию
скилл CX Codex

zenstack-plugin-dev — скилл для Claude Code: разработка плагинов

Скилл zenstack-plugin-dev для Claude Code помогает создавать плагины ZenStack V3. Включается при работе с ZModel, генерацией кода через CLI или расширением ORM-клиента.

MIT 521 установок ★ 3 обновлён 2026-10-28

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add zenstackhq/skills --skill zenstack-plugin-dev -a claude-code
Открыть на GitHub

Что делает zenstack-plugin-dev

Скилл описывает разработку плагинов ZenStack V3 на уровне схемы, CLI и ORM. Он разбирает пользовательские атрибуты и функции ZModel, генераторы для zen generate и runtime-плагины с перехватчиками запросов и событий мутаций.

В руководстве показаны расширение клиента, дополнительные аргументы запросов и вычисляемые поля результата. Для CLI-плагинов нужен ESM-модуль с экспортом CliPlugin; SDK устанавливается командой npm install -D @zenstackhq/sdk. Runtime-типы предоставляет @zenstackhq/orm.

Плагины ZenStack V3 имеют статус preview и могут измениться в будущих версиях. Хуки мутаций не перехватывают изменения, вызванные каскадами базы данных; загрузка строк в массовых мутациях может быть затратной.

Какие задачи решает

  • добавить пользовательские атрибуты и функции в ZModel
  • создать генератор артефактов для zen generate
  • перехватывать ORM-запросы и менять SQL
  • расширить клиент собственными методами и свойствами
  • вычислять виртуальные поля из результатов запросов

Примеры запросов агенту

  • Создай runtime-плагин ZenStack с хуком onQuery для перехвата ORM-операций.
  • Добавь CLI-плагин для zen generate, который создаёт отчёт по моделям ZModel.
  • Расширь клиент ZenStack пользовательским методом и вычисляемым полем результата.

Как установить zenstack-plugin-dev

1Через Skills CLI (Vercel)

npx skills add zenstackhq/skills --skill zenstack-plugin-dev -a claude-code

2Вручную: положить файлы

~/.claude/skills/zenstack-plugin-dev/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/zenstack-plugin-dev/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о zenstack-plugin-dev

Как установить zenstack-plugin-dev в Claude Code?

Выполни npx skills add zenstackhq/skills --skill zenstack-plugin-dev -a claude-code. Файл скилла находится по пути ~/.claude/skills/zenstack-plugin-dev/SKILL.md.

Что делает zenstack-plugin-dev?

Он помогает разрабатывать плагины ZenStack V3 для схемы ZModel, генерации через CLI и ORM-клиента. Включает работу с перехватчиками, аргументами запросов и вычисляемыми полями.

Что нужно для разработки CLI-плагина ZenStack?

CLI-плагин должен быть ESM-модулем с экспортом CliPlugin по умолчанию. Для типов CLI и AST устанавливается @zenstackhq/sdk командой npm install -D @zenstackhq/sdk.

Исходный текст

SKILL.md · MIT
---
name: zenstack-plugin-dev
description: Develop ZenStack V3 plugins. Use when building or declaring a plugin — custom ZModel attributes/functions, CLI code generators (CliPlugin with a generate callback for `zen generate`), or runtime plugins installed via $use/definePlugin (onQuery, onKyselyQuery, onEntityMutation hooks, extending the client, custom query args, computed result fields).
---

# ZenStack V3 — Plugin Development

> Plugins are a **preview** feature and may change in future releases.

A ZenStack plugin can extend the toolkit at **three levels**, independently or together:

1. **Schema (ZModel)** — contribute custom attributes (e.g. `@password`) and functions to the
   schema language.
2. **CLI (code generation)** — participate in `zen generate` to emit artifacts from the schema.
3. **Runtime (ORM)** — install on the client to intercept queries, hook CRUD lifecycle events,
   transform SQL, add custom methods, or compute fields.

ZenStack's `plugin` replaces Prisma's `generator`. To declare/consume plugins in a schema see
`zenstack-schema-modeling`; this skill is about *authoring* them.

Packages: `@zenstackhq/orm` (runtime plugin types), `@zenstackhq/sdk` (CLI plugin types + ZModel
AST). Install the SDK as a dev dependency: `npm install -D @zenstackhq/sdk`.

## Declaring a plugin in ZModel

```zmodel
plugin myPlugin {
    provider = './my-plugin'   // local .ts/.js/.mts/.mjs file, a folder with an index, or an npm package
    output   = './generated'   // arbitrary key=value options, readable by the plugin
}
```

`provider` resolution order: local file path → folder with an index → npm package. CLI plugins must
be **ESM**; TypeScript providers are loaded via [jiti](https://github.com/unjs/jiti). The built-in
`@core/typescript` plugin runs automatically; `@core/prisma` emits a Prisma schema.

## Runtime plugins

A runtime plugin is an object implementing `RuntimePlugin` from `@zenstackhq/orm`. Define it three
ways; `definePlugin` gives the best type inference:

```ts
import { definePlugin, type RuntimePlugin } from '@zenstackhq/orm';

// plain object / definePlugin (recommended)
const plugin = definePlugin({ id: 'my-plugin', /* hooks… */ });

// or a class
class MyPlugin implements RuntimePlugin<typeof schema> {
    id = 'my-plugin';
    /* hooks… */
}
```

Install on the client (immutable — returns a new client, original unchanged); remove with
`$unuse(id)` / `$unuseAll()`. You can also pass `plugins: [...]` to the `ZenStackClient` constructor.

```ts
const db = new ZenStackClient(schema, { dialect });
const withPlugin = db.$use(plugin);              // new client
const plain = withPlugin.$unuse('my-plugin');    // remove by id
// or: new ZenStackClient(schema, { dialect, plugins: [plugin] });
```

Every plugin needs a unique `id`. Add any combination of the hooks below.

### `onQuery` — intercept ORM operations

Fires for ORM API calls only (`findMany`, `create`, …), **not** the query builder. Wrap, modify
args, short-circuit, or post-process results via `proceed`.

```ts
definePlugin({
    id: 'timing',
    onQuery: async ({ model, operation, args, proceed }) => {
        const start = Date.now();
        const result = await proceed(args);
        console.log(`${model}.${operation} took ${Date.now() - start}ms`);
        return result;
    },
});
```

### `onKyselyQuery` — intercept/transform SQL

The lowest-level hook: every DB access (ORM *and* query builder) flows through Kysely here, so you
can inspect or rewrite the SQL AST (`OperationNode`) before `proceed`. Good for soft-deletes,
injected filters, column transforms.

```ts
import type { OnKyselyQueryCallback } from '@zenstackhq/orm';

const hook: OnKyselyQueryCallback<typeof schema> = async ({ query, proceed }) => {
    // inspect/transform `query` (a Kysely OperationNode), e.g. with an OperationNodeTransformer
    return proceed(query);
};
definePlugin({ id: 'sql-rewrite', onKyselyQuery: hook });
```

### `onEntityMutation` — before/after create·update·delete

Lifecycle hooks around entity mutations, with lazy loaders for the affected rows.

```ts
definePlugin({
    id: 'audit',
    onEntityMutation: {
        runAfterMutationWithinTransaction: false, // default: run after the tx commits
        async beforeEntityMutation({ model, action, loadBeforeMutationEntities }) {
            // action: 'create' | 'update' | 'delete'
            if (model === 'Post' && action === 'update') {
                const before = await loadBeforeMutationEntities();
            }
        },
        async afterEntityMutation({ model, action, loadAfterMutationEntities }) {
            const after = await loadAfterMutationEntities();
        },
    },
});
```

Set `runAfterMutationWithinTransaction: true` to run the after-hook atomically inside the mutation's
transaction. Note: mutations triggered by DB cascades are **not** captured, and the loaders can be
expensive on bulk mutations.

### Extending the client (`client`)

Add custom methods/properties under `client`. Names **must be `$`-prefixed** so they don't shadow
model accessors; grouping under one `$namespace` object is recommended.

```ts
const cacheDb = db.$use(definePlugin({
    id: 'cache',
    client: {
        $cache: {
            get stats() { return { hits: 0, misses: 0 }; },
            async invalidate() { /* … */ },
        },
    },
}));
await cacheDb.$cache.invalidate();
```

### Custom query args (`queryArgs`)

Accept extra options on ORM calls, validated with a Zod schema. Target `$all`, the
`$create`/`$read`/`$update`/`$delete` groups, or specific operations.

```ts
import { z } from 'zod';

definePlugin({
    id: 'cache',
    queryArgs: {
        $read: z.object({ cache: z.strictObject({ ttl: z.number().positive().optional() }).optional() }),
    },
    onQuery: ({ args, proceed }) => proceed(args), // read (args as any).cache
});
// await db.user.findMany({ where: {...}, cache: { ttl: 60 } });
```

### Computed result fields (`result`, v3.5.0+)

Add virtual fields computed after a query from declared `needs` fields.

```ts
definePlugin({
    id: 'full-name',
    result: {
        user: {
            fullName: {
                needs: { firstName: true, lastName: true },
                compute: (user) => `${user.firstName} ${user.lastName}`,
            },
        },
    },
});
```

## CLI plugins (code generation)

A CLI plugin is an ESM module whose **default export** is a `CliPlugin` with a `generate` callback.
It runs during `zen generate`, receiving the parsed ZModel AST.

```ts
import type { CliPlugin } from '@zenstackhq/sdk';
import { isDataModel, type InvocationExpr } from '@zenstackhq/sdk/ast';
import fs from 'node:fs';

const plugin: CliPlugin = {
    name: 'Password Report',
    // statusText is optional
    generate: ({ model, defaultOutputPath, pluginOptions }) => {
        if (pluginOptions['report'] !== true) return;       // options come from the ZModel plugin block
        let out = '# Password Fields\n\n';
        for (const dm of model.declarations.filter(isDataModel)) {
            for (const field of dm.fields) {
                const attr = field.attributes.find((a) => a.decl.$refText === '@password');
                if (attr) out += `- ${dm.name}.${field.name}\n`;
            }
        }
        fs.writeFileSync(`${defaultOutputPath}/password-fields.md`, out, 'utf-8');
    },
};
export default plugin;
```

`generate` receives `{ model, defaultOutputPath, pluginOptions }` — the ZModel AST, the resolved
output directory (the `output` option or a default), and the options from the `plugin` block.

## Schema plugins (custom attributes & functions)

Declare new ZModel attributes/functions in a `.zmodel` the plugin ships, then use them in the app
schema. `@@@targetField` constrains where an attribute applies.

```zmodel
// my-plugin/plugin.zmodel
attribute @password(hasher: Any) @@@targetField([StringField])
function bcryptHasher(rounds: Int): Any {}
```

```zmodel
// app schema
model User {
    id       Int    @id @default(autoincrement())
    password String @password(hasher: bcryptHasher(10))
}
```

## End-to-end pattern: password hasher

The docs' worked example combines all three levels into one plugin package:

1. **Schema** — `plugin.zmodel` defines `@password` + `bcryptHasher()`; the app schema applies
   `@password(hasher: bcryptHasher(10))` to a field.
2. **CLI** — a `CliPlugin.generate` walks the AST and emits a "password fields" report when the
   `report` option is set.
3. **Runtime** — a `RuntimePlugin` with `onKyselyQuery` uses a Kysely `OperationNodeTransformer` to
   detect `@password` fields (via `schema.models[...].fields[...].attributes`) and hash values on
   `INSERT`/`UPDATE` before they hit the database.

Install with `db.$use(new PasswordHasherPlugin())` (or the `plugins` constructor option), then
`npm install -D @zenstackhq/sdk` and `zen generate` to run the CLI side.

> Use **Zod v4** for `queryArgs` schemas to match ZenStack's bundled version.

## Reference docs

Full ZenStack documentation for this topic is bundled under [`references/`](references/):

- [plugin-dev.md](references/plugin-dev.md) — end-to-end plugin development guide
- [runtime-plugins-overview.md](references/runtime-plugins-overview.md) — runtime plugin model
- [extending-orm-client.md](references/extending-orm-client.md) — client methods, query args, computed fields
- [entity-mutation-hooks.md](references/entity-mutation-hooks.md) — before/after mutation hooks
- [kysely-query-hooks.md](references/kysely-query-hooks.md) — `onKyselyQuery` SQL transformation
- [query-api-hooks.md](references/query-api-hooks.md) — `onQuery` ORM interception
- [zmodel-plugin.md](references/zmodel-plugin.md) — declaring plugins in ZModel
- [zmodel-plugin-reference.md](references/zmodel-plugin-reference.md) — `plugin` block reference

© zenstackhq · MIT · zenstackhq/skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
typeorm Mindrally Скилл typeorm для Claude Code помогает писать код с TypeORM на TypeScript и JavaScript. Включается при работе с сущностями, связями и запросами к базе данных. CX Codex +1 2 100установок drizzle bobmatnyc Скилл drizzle для Claude Code помогает писать типобезопасный SQL-код с Drizzle ORM. Подключается при работе с drizzle-orm и связанной функциональностью. CX Codex +1 1 900установок sequelize Mindrally Задаёт агенту правила разработки на Sequelize: модели, ассоциации, миграции и запросы к реляционным базам в Node.js проектах. CX Codex +1 1 000установок drizzle-best-practices Marc A. Maceira Zayas Скилл drizzle-best-practices для Claude Code и других агентов: подсказывает, как писать схемы, запросы и связи в Drizzle ORM на PostgreSQL в TypeScript-проекте. CX Codex +1 718установок bun-drizzle-integration secondsky Скилл bun-drizzle-integration подсказывает агенту, как связать Drizzle ORM с драйвером bun:sqlite: схема, миграции, CRUD и транзакции в одном месте. CX Codex +1 438установок prisma-client-api prisma Справочник по Prisma Client API для написания запросов к БД, CRUD-операций и фильтрации. Срабатывает на упоминания findMany, create, update, delete и транзакций. CX Codex +1 441 400установок

Из того же набора9

zenstack-access-control Скилл zenstack-access-control для Claude Code помогает задавать правила доступа в схеме ZenStack V3. Подключается при работе с @@allow, @@deny, auth() и проверками после обновления. CX Codex +1 556установок zenstack-db-migration Скилл zenstack-db-migration для Claude Code управляет миграциями схемы базы данных в ZenStack V3. Вызывается при создании и применении миграций, синхронизации схемы или работе с существующей базой. CX Codex +1 551установок zenstack-crud-server Скилл zenstack-crud-server для Claude Code превращает модели ZenStack V3 в REST- или RPC CRUD API. Подключается при создании серверных маршрутов, настройке доступа к данным или вызове API из клиента. CX Codex +1 548установок zenstack-migrate-from-prisma Скилл zenstack-migrate-from-prisma для Claude Code переносит проект с Prisma на ZenStack V3. Он помогает заменить схему, клиент и команды миграции, сохранив рабочие вызовы ORM. CX Codex +1 520установок zenstack-migrate-from-v2 Скилл zenstack-migrate-from-v2 для Claude Code переводит проект ZenStack с V2 на V3. Помогает обновить схему, политики доступа, серверные адаптеры и клиентские хуки. CX Codex +1 515установок zenstack-project-setup Скилл zenstack-project-setup для Claude Code настраивает проекты ZenStack V3: устанавливает зависимости, создаёт каркас и запускает команды zen. Активируется при установке ZenStack, создании проекта или работе с CLI. CX Codex +1 510установок zenstack-querying Скилл zenstack-querying для Claude Code помогает работать с данными через клиент ZenStack V3. Он включается при создании запросов, изменении записей и настройке выборок со связями. CX Codex +1 494установок zenstack-schema-modeling Скилл zenstack-schema-modeling для Claude Code помогает создавать и менять схемы данных ZModel для ZenStack V3. Запускается при работе с моделями, полями, связями, перечислениями и типизированными JSON-полями. CX Codex +1 470установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой