heyapi-plugin-author
/heyapi-plugin-author
Write a `@hey-api/openapi-ts` plugin that emits custom codegen on top of hey-api's IR. Use when the user wants to add a TypeScript code generator that hooks into hey-api's spec → IR pipeline — custom validators, mock factories, RPC clients, route maps, framework adapters, anything hey-api doesn't ship. The ir-kit repo already has five reference plugins (`openapi-ts-faker`, `openapi-ts-orpc`, `openapi-ts-paths`, `openapi-ts-typia`, `openapi-ts-k6`) that serve as templates. Triggers on "hey-api plugin", "openapi-ts plugin", "custom codegen plugin", "extend hey-api", `definePluginConfig`, `define
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 21.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Write a `@hey-api/openapi-ts` plugin that emits custom codegen on top of hey-api's IR. Use when the user wants to add a TypeScript code generator that hooks into hey-api's spec → IR pipeline — custom validators, mock factories, RPC clients, route maps, framework adapters, anything hey-api doesn't ship. The ir-kit repo already has five reference plugins (`openapi-ts-faker`, `openapi-ts-orpc`, `openapi-ts-paths`, `openapi-ts-typia`, `openapi-ts-k6`) that serve as templates. Triggers on "hey-api plugin", "openapi-ts plugin", "custom codegen plugin", "extend hey-api", `definePluginConfig`, `define
Triggers from the description
Original author description
Write a `@hey-api/openapi-ts` plugin that emits custom codegen on top of hey-api's IR. Use when the user wants to add a TypeScript code generator that hooks into hey-api's spec → IR pipeline — custom validators, mock factories, RPC clients, route maps, framework adapters, anything hey-api doesn't ship. The ir-kit repo already has five reference plugins (`openapi-ts-faker`, `openapi-ts-orpc`, `openapi-ts-paths`, `openapi-ts-typia`, `openapi-ts-k6`) that serve as templates. Triggers on "hey-api plugin", "openapi-ts plugin", "custom codegen plugin", "extend hey-api", `definePluginConfig`, `define
How it works
- When to reach for this
- Plugin anatomy
- Minimal plugin
- Reference plugins — copy these
- How hey-api wires your plugin
- The IR you'll be walking
- Code generation: use $ DSL or ts.factory
- Common pitfalls
- How AI agents should use this
SKILL.md preview
---
name: heyapi-plugin-author
description: Write a `@hey-api/openapi-ts` plugin that emits custom codegen on top of hey-api's IR. Use when the user wants to add a TypeScript code generator that hooks into hey-api's spec → IR pipeline — custom validators, mock factories, RPC clients, route maps, framework adapters, anything hey-api doesn't ship. The ir-kit repo already has five reference plugins (`openapi-ts-faker`, `openapi-ts-orpc`, `openapi-ts-paths`, `openapi-ts-typia`, `openapi-ts-k6`) that serve as templates. Triggers on "hey-api plugin", "openapi-ts plugin", "custom codegen plugin", "extend hey-api", `definePluginConfig`, `definePlugin`, "openapi-ts hooks", "openapi-ts plugin author". Do NOT use for hey-api consumption (use openapi-sdk → `@ir-kit/openapi-typescript`) or for non-hey-api codegen (see openapi-sdk for go/kotlin/swift, asyncapi-typescript for AsyncAPI).
---
# Authoring a `@hey-api/openapi-ts` plugin
hey-api's plugin model lets you drop a new code generator into the spec → IR → emit pipeline. Five reference plugins live in this monorepo at `packages/openapi/plugins/` (`faker`, `orpc`, `paths`, `typia`) and at `packages/k6/hey-api/` (`openapi-ts-k6`). Copy whichever has the closest shape to your target.
## When to reach for this
- User wants codegen that hey-api doesn't ship — faker factories, oRPC clients, route consts, typia validators, k6 clients, RPC clients for a different framework.
- User wants to compose with existing hey-api plugins (`@hey-api/typescript`, `@hey-api/sdk`) — depend on them via `dependencies` so the order is right.
- User is extending an existing plugin and wants the canonical shape.
Skip this skill for: consuming hey-api (the user just wants `generate({ input, output })` → see `openapi-sdk`), or non-hey-api codegen.
## Plugin anatomy
Every hey-api plugin is **four files**:
```text
my-plugin/
├── src/
│ ├── index.ts # exports defineConfig + types (the public surface)
│ ├── config.ts # defaultConfig + the definePluginConfig wrapper
│ ├── plugin.ts # handler() — the actual codegen logic
│ └── types.ts # UserConfig + Config + module augmentation
└── package.json
```
See [references/plugin-anatomy.md](references/plugin-anatomy.md) for the full walkthrough of each file using `@ir-kit/openapi-ts-paths` (the simplest reference plugin — 4 files, ~150 lines total).
## Minimal plugin
### `types.ts`
```ts
import type { DefinePlugin, Plugin } from "@hey-api/shared";
export type UserConfig = Plugin.Hooks &
Plugin.UserExports & {
name: "@my-org/my-plugin";
/** Filename (no extension). @default "my-output" */
output?: string;
};
export type Config = Plugin.Hooks &
Plugin.Exports & {
name: "@my-org/my-plugin";
output: string;
};
export type MyPlugin = DefinePlugin<UserConfig, Config>;
// Module augmentation — registers your plugin in hey-api's plugin map
declare module "@hey-api/openapi-ts" {
export interface PluginConfigMap {
"@my-org/my-plugin": MyPlugin;
}
}
```
### `config.ts`
```ts
import { definePluginConfig } from "@hey-api/shared";
import { handler } from "./plugin.js";
import type { MyPlugin } from "./types.js";
export const defaultConfig: MyPlugin["Config"] = {
config: { output: "my-output" },
dependencies: ["@hey-api/typescript"], // depend on TS plugin so types resolve
handler,
name: "@my-org/my-plugin",
tags: ["transformer"],
};
export const defineConfig = definePluginConfig(defaultConfig);
```
### `plugin.ts` — the codegen handler
```ts
import type { MyPlugin } from "./types.js";
export const handler: MyPlugin["Handler"] = ({ plugin }) => {
// plugin.context — global pipeline context
// plugin.config — your resolved config (filled in by definePluginConfig)
// plugin.file({...}) — register a file to emit
// plugin.forEach("operation", (event) => ...) — iterate ops
// plugin.forEach("schema", (event) => ...) — iterate schemas
const file = plugin.createFile({
id: plugin.name,
path: plugin.config.output,
});
plugin.forEach("operation", (event) => {
// event.operation has: id, method, path, parameters, body, responses
file.add(/* TsDsl node */);
});
};
```
### `index.ts`
```ts
import "./types.js"; // side-effect import for module augmentation
export { defaultConfig, defineConfig } from "./config.js";
export type { MyPlugin } from "./types.js";
```
## Reference plugins — copy these
The ir-kit monorepo ships five plugins. Each demonstrates a different pattern:
| Plugin | Pattern | LoC |
|---|---|---|
| [`@ir-kit/openapi-ts-paths`](https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/plugins/paths) | Simplest — per-operation route consts. Best starting point. | ~150 |
| [`@ir-kit/openapi-ts-faker`](https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/plugins/faker) | Schema-driven — emits faker factories per top-level schema. Shows schema iteration. | ~600 |
| [`@ir-kit/openapi-ts-typia`](https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/plugins/typia) | Validator emission — types → typia validators. Shows IR walking + format hints. | ~400 |
| [`@ir-kit/openapi-ts-orpc`](https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/plugins/orpc) | Multi-file emission — oRPC clients + contract + server. Largest of the set. | ~800 |
| [`@ir-kit/openapi-ts-k6`](https://github.com/ir-kit/ir-kit/tree/main/packages/k6/hey-api) | Thin delegator — defers all real work to `@ir-kit/k6-gen`. Shows "plugin as adapter". | ~30 |
**Start with `openapi-ts-paths`** if you're new — smallest surface, complete shape.
## How hey-api wires your plugin
When a consumer does:
```ts
import { defineConfig as myPlugin } from "@my-org/my-plugin";
await createClient({
input: "./openapi.yaml",
output: "./client",
plugins: ["@hey-api/typescript", "@hey-api/sdk", myPlugin({ output: "routes" })],
});
```
…hey-api:
1. Parses the spec into an IR (`ir.paths`, `ir.components.schemas`, …).
2. Resolves the plugin order via `dependencies` (`@hey-api/typescript` runs before yours).
3. Calls each plugin's `handler({ plugin })`.
4. The handler emits files via `plugin.createFile(...).add(...)`.
5. hey-api writes everything to disk + runs format/lint passes.
Your plugin doesn't write to disk directly — it registers nodes via the DSL or `createFile`.
## The IR you'll be walking
hey-api's IR is documented in `@hey-api/shared`'s exported types. The shapes you'll touch most:
- `IR.OperationObject` — `id`, `method`, `path`, `parameters: { path?, query?, header?, cookie? }`, `body?`, `responses`
- `IR.SchemaObject` — type-tagged union (`string`, `number`, `enum`, `object`, `array`, `tuple`, plus composed shapes with `items`). The ir-kit repo has `@ir-kit/openapi-tools` with helpers — `getEnumLiterals`, `isEnumSchema`, `isUnionSchema` — that handle the common dispatch traps.
## Code generation: use `$` DSL or `ts.factory`
Convention across ir-kit: **no template strings for spec-driven generation**. Use hey-api's `$` DSL (`import { $ } from "@hey-api/openapi-ts"`) or `ts.factory` directly. The DSL has gaps (no `$.import`, no `$.interface`, no statement-level `$.raw`), so import declarations and interface declarations drop to `ts.factory` directly via small helpers.
See `packages/k6/codegen/src/emit/ast-imports.ts` in the repo for a reusable `namedImport` / `namespaceImport` helper pair.
## Common pitfalls
- **Plugin name must be a string literal** (e.g. `"@my-org/my-plugin"`), used in the module augmentation, in the `name` field, and as the dependency string. Mismatch → silent skip.
- **`dependencies` are plugin names, not npm package names.** They reference hey-api plugins by their `name` field.
- **Module augmentation must run.** That's why `index.ts` does `import "./types.js"` for side effects — it triggers the `declare module "@hey-api/openapi-ts"` augmentation. Without it, hey-api doesn't know about your plugin.
- **Emit through `plugin.createFile`, not direct `fs`.** hey-api owns disk writes; your handler stays pure.
- **Walk via `plugin.forEach("operation" | "schema", ...)`**, not by traversing `ir.paths` directly — the helper does the path-method-method canonicalization for you.
## How AI agents should use this
1. Ask which kind of plugin: types-only / schema-driven / validators / multi-file / framework adapter.
2. Match to the closest reference plugin and tell the user to copy that as a template.
3. Load [references/plugin-anatomy.md](references/plugin-anatomy.md) when they need the four-file shape explained line-by-line.
4. For DSL questions ("how do I emit an interface", "how do I emit an import"), point at `packages/k6/codegen/src/emit/ast-imports.ts` in the repo for the AST helper pattern.
5. For IR walking, point at `@ir-kit/openapi-tools` (specifically `getEnumLiterals` / `isEnumSchema` / `isUnionSchema`) — the schema-dispatch helpers shared across all ir-kit generators.
Files in this package (2)
- SKILL.md 9 KB
- references/plugin-anatomy.md 7 KB
Versions
The database has no other skills named heyapi-plugin-author.
Database snapshot: 13.11.2026 · package version 518e21a603cc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100openapi-sdk
Generate idiomatic native SDK clients (Go, Kotlin, Swift, or TypeScript) from an OpenAPI 3.x spec using `@ir-kit/openapi-{go,kotlin,swift,typescript}`. Each generator emits language-native code — Go uses `net/http` + `encoding/json` + `context.Context`, Kotlin uses OkHttp +… - 100openapi-codegen
OpenAPI client code generation. Covers openapi-typescript, openapi-generator-cli, swagger-typescript-api, and trpc-openapi. Use for generating type-safe API clients. USE WHEN: user mentions "OpenAPI codegen", "generate API client", "openapi-typescript", "swagger-typescript-api",… - 100openapi-generator
OpenAPI Generator - generate clients and servers from OpenAPI specs USE WHEN: user mentions "OpenAPI Generator CLI", "generate Java client", "generate Spring server", "openapi-generator-cli", "openapi-generator-maven-plugin", asks about "generate server from OpenAPI", "OpenAPI… - 95codegen-api
Set up typesafe API code generation in 2026, preferring framework-agnostic options factories over generated hooks. Walks the decision matrix for REST (OpenAPI via hey-api) and GraphQL (graphql-codegen client preset, gql.tada), wires the minimal config for the chosen stack, and… - 100ir-kit-migrate
Migrate a project from the legacy `@ahmedrowaihi/*` npm scope to the new `@ir-kit/*` scope. Rewrites `import` / `require` statements across TypeScript / JavaScript files, updates `package.json` dependencies, and (optionally) refreshes lockfile + verifies the build. Use when the… - 100openapi-spec-generator
Generate openapi spec generator operations. Auto-activating skill for API Development. Triggers on: openapi spec generator, openapi spec generator Part of the API Development skill category. Use when working with APIs or building integrations. Trigger with phrases like "openapi…