Skip to main content
skill CX Codex

zenstack-plugin-dev — Claude Code skill for plugin development

The zenstack-plugin-dev Claude Code skill guides development of ZenStack V3 plugins. It applies to ZModel extensions, CLI code generation, and ORM client plugins.

MIT 521 installs ★ 3 updated 2026-10-28

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add zenstackhq/skills --skill zenstack-plugin-dev -a claude-code
Open on GitHub

What zenstack-plugin-dev does

The skill covers ZenStack V3 plugin work across the schema, CLI, and ORM layers. It explains custom ZModel attributes and functions, generators for zen generate, and runtime hooks for ORM queries and entity mutations.

It also describes adding client methods, accepting extra query arguments, and computing virtual result fields. A CLI plugin must be an ESM module with a default CliPlugin export; install the SDK with npm install -D @zenstackhq/sdk. Runtime plugin types come from @zenstackhq/orm.

ZenStack V3 plugins are a preview feature and may change in later releases. Mutation hooks miss changes caused by database cascades, and loading rows for bulk mutations can be expensive.

What it helps with

  • add custom attributes and functions to ZModel
  • generate artifacts from a schema with zen generate
  • intercept ORM calls or transform SQL
  • extend the client with custom methods and properties
  • compute virtual fields from query results

Example prompts for the agent

  • Add an onQuery hook to a ZenStack runtime plugin to intercept ORM operations.
  • Create a CLI plugin for zen generate that produces a report from ZModel models.
  • Extend the ZenStack client with a custom method and a computed result field.

How to install zenstack-plugin-dev

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/zenstack-plugin-dev/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about zenstack-plugin-dev

How do I install zenstack-plugin-dev in Claude Code?

Run npx skills add zenstackhq/skills --skill zenstack-plugin-dev -a claude-code. The skill file is at ~/.claude/skills/zenstack-plugin-dev/SKILL.md.

What does zenstack-plugin-dev do?

It guides development of ZenStack V3 plugins for ZModel, CLI generation, and the ORM client. Topics include hooks, custom query arguments, and computed result fields.

What does a ZenStack CLI plugin need?

It must be an ESM module whose default export is a CliPlugin. Install @zenstackhq/sdk for CLI plugin types and the ZModel AST with npm install -D @zenstackhq/sdk.

Source text

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

Similar skills

All skills for Backend and APIs →

From the same set9

zenstack-access-control The zenstack-access-control Claude Code skill helps define access policies in a ZenStack V3 schema. It activates for @@allow, @@deny, auth(), and post-update rules. CX Codex +1 556installs zenstack-db-migration The zenstack-db-migration Claude Code skill manages database schema migrations in ZenStack V3. It activates for migration work, schema prototyping, or introspecting an existing database. CX Codex +1 551installs zenstack-crud-server zenstack-crud-server — a skill for Claude Code that turns ZenStack V3 models into REST or RPC CRUD APIs. It covers server routes, per-request access control, OpenAPI specs, and client calls. CX Codex +1 548installs zenstack-migrate-from-prisma The zenstack-migrate-from-prisma Claude Code skill guides a project migration from Prisma to ZenStack V3. It covers schema, client, generation, and migration updates. CX Codex +1 520installs zenstack-migrate-from-v2 The zenstack-migrate-from-v2 skill for Claude Code guides a ZenStack project upgrade from V2 to V3. It covers schema, access policies, server adapters, and client hooks. CX Codex +1 515installs zenstack-project-setup The zenstack-project-setup Claude Code skill sets up ZenStack V3 projects, scaffolds new ones, and runs zen CLI tasks. It activates for ZenStack installation, project creation, or CLI use. CX Codex +1 510installs zenstack-querying The zenstack-querying Claude Code skill explains how to query and change data with the ZenStack V3 client. It covers ORM operations, relations, and SQL-shaped queries built with Kysely. CX Codex +1 494installs zenstack-schema-modeling The zenstack-schema-modeling Claude Code skill helps write and revise ZModel schemas for ZenStack V3. It activates for work on models, fields, relations, enums, and typed JSON fields. CX Codex +1 470installs

Project sponsors

Companies that keep this analytics open