@trpc/openapi 11.14.0-alpha → 11.14.1-canary.0

package/README.md

@@ -38,6 +38,14 @@ The generator statically analyses your router's TypeScript types — it never ex
 
 Full documentation is available at [trpc.io/docs/openapi](https://trpc.io/docs/openapi).
 
+## AI Agents
+
+If you use an AI coding agent, install tRPC skills for better code generation:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
 ## TODO
 
 - [ ] SSE subscriptions

package/bin/intent.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library');
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.');
+    console.error('');
+    console.error('Install it as a dev dependency:');
+    console.error('  npm add -D @tanstack/intent');
+    console.error('');
+    console.error('Or run directly:');
+    console.error('  npx @tanstack/intent@latest list');
+    process.exit(1);
+  }
+  throw e;
+}

package/package.json

@@ -2,12 +2,13 @@
   "name": "@trpc/openapi",
   "type": "module",
   "sideEffects": false,
-  "version": "11.14.0-alpha",
+  "version": "11.14.1-canary.0+e39a654b3",
   "description": "OpenAPI document generator for tRPC routers",
   "author": "KATT",
   "license": "MIT",
   "bin": {
-    "trpc-openapi": "./dist/cli.js"
+    "trpc-openapi": "./dist/cli.js",
+    "intent": "./bin/intent.js"
   },
   "homepage": "https://trpc.io",
   "repository": {
@@ -64,7 +65,10 @@
     "!**/*.test.*",
     "!**/__tests__",
     "!test",
-    "heyapi"
+    "heyapi",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "publishConfig": {
     "access": "public"
@@ -72,7 +76,8 @@
   "devDependencies": {
     "@hey-api/openapi-ts": "^0.94.1",
     "@swagger-api/apidom-ls": "^1.6.0",
-    "@trpc/server": "11.14.0",
+    "@tanstack/intent": "^0.0.20",
+    "@trpc/server": "11.14.1",
     "@types/node": "^22.13.5",
     "bson": "^7.2.0",
     "eslint": "^9.26.0",
@@ -85,7 +90,7 @@
   },
   "peerDependencies": {
     "@hey-api/openapi-ts": ">=0.13.0",
-    "@trpc/server": "11.14.0",
+    "@trpc/server": "11.14.1",
     "typescript": ">=5.7.2",
     "zod": ">=4.0.0"
   },
@@ -100,5 +105,8 @@
   "funding": [
     "https://trpc.io/sponsor"
   ],
-  "gitHead": "6e03f5c2f8d8ebaa237747d2db447737393402c6"
+  "keywords": [
+    "tanstack-intent"
+  ],
+  "gitHead": "e39a654b306d0c75730a9c546e77333f9d1dca8c"
 }

package/skills/openapi/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: openapi
+description: >
+  Generate OpenAPI 3.1 spec from a tRPC router with @trpc/openapi CLI or
+  programmatic API. Generate typed REST client with @hey-api/openapi-ts and
+  configureTRPCHeyApiClient(). Configure transformers (superjson, EJSON) for
+  generated clients. Alpha status.
+type: composition
+library: trpc
+library_version: '11.14.0-alpha'
+requires:
+  - server-setup
+sources:
+  - 'trpc/trpc:www/docs/client/openapi.md'
+  - 'trpc/trpc:packages/openapi/test/heyapi.test.ts'
+  - 'trpc/trpc:examples/openapi-codegen/'
+---
+
+# tRPC -- OpenAPI
+
+> **Alpha**: `@trpc/openapi` is versioned as `11.x.x-alpha`. APIs may change without notice.
+
+## Setup
+
+### 1. Install
+
+```bash
+pnpm add @trpc/openapi
+```
+
+For HeyAPI client generation:
+
+```bash
+pnpm add @hey-api/openapi-ts -D
+```
+
+### 2. Generate the OpenAPI spec
+
+The generator statically analyses your router's TypeScript types. It never executes your code.
+
+**CLI:**
+
+```bash
+pnpm exec trpc-openapi ./src/server/index.ts -e appRouter -o openapi.json --title "My API" --version 1.0.0
+```
+
+| Option                | Default        | Description                 |
+| --------------------- | -------------- | --------------------------- |
+| `-e, --export <name>` | `AppRouter`    | Name of the exported router |
+| `-o, --output <file>` | `openapi.json` | Output file path            |
+| `--title <text>`      | `tRPC API`     | OpenAPI `info.title`        |
+| `--version <ver>`     | `0.0.0`        | OpenAPI `info.version`      |
+
+**Programmatic:**
+
+```ts
+import { generateOpenAPIDocument } from '@trpc/openapi';
+
+const doc = await generateOpenAPIDocument('./src/server/index.ts', {
+  exportName: 'appRouter',
+  title: 'My API',
+  version: '1.0.0',
+});
+```
+
+### 3. Generate a HeyAPI client from the spec
+
+```ts
+// scripts/codegen.ts
+import { rmSync, writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createClient } from '@hey-api/openapi-ts';
+import { generateOpenAPIDocument } from '@trpc/openapi';
+import { createTRPCHeyApiTypeResolvers } from '@trpc/openapi/heyapi';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const routerPath = path.resolve(__dirname, '..', 'server', 'index.ts');
+const outputDir = path.resolve(__dirname, '..', 'client', 'generated');
+const specPath = path.resolve(__dirname, '..', '..', 'openapi.json');
+
+async function main() {
+  const doc = await generateOpenAPIDocument(routerPath, {
+    exportName: 'appRouter',
+    title: 'Example API',
+    version: '1.0.0',
+  });
+
+  writeFileSync(specPath, JSON.stringify(doc, null, 2) + '\n');
+
+  rmSync(outputDir, { recursive: true, force: true });
+
+  await createClient({
+    input: specPath,
+    output: outputDir,
+    plugins: [
+      {
+        name: '@hey-api/typescript',
+        '~resolvers': createTRPCHeyApiTypeResolvers(),
+      },
+      {
+        name: '@hey-api/sdk',
+        operations: { strategy: 'single' },
+      },
+    ],
+  });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+Run it:
+
+```bash
+pnpm tsx scripts/codegen.ts
+```
+
+### 4. Configure and use the generated client at runtime
+
+```ts
+import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
+import { client } from './generated/client.gen';
+import { Sdk } from './generated/sdk.gen';
+
+configureTRPCHeyApiClient(client, {
+  baseUrl: 'http://localhost:3000',
+});
+const sdk = new Sdk({ client });
+
+// Queries -> GET, Mutations -> POST
+const result = await sdk.greeting({ query: { input: { name: 'World' } } });
+const user = await sdk.user.create({ body: { name: 'Bob', age: 30 } });
+```
+
+## Core Patterns
+
+### CLI quick spec generation
+
+```bash
+# Default export name "AppRouter", output "openapi.json"
+pnpm exec trpc-openapi ./src/server/router.ts
+
+# Custom export name and output
+pnpm exec trpc-openapi ./src/server/router.ts -e appRouter -o api.json --title "My API" --version 1.0.0
+```
+
+### HeyAPI codegen with type resolvers (transformer setup)
+
+When the server uses a transformer, pass `createTRPCHeyApiTypeResolvers()` to the `@hey-api/typescript` plugin so generated types use `Date` instead of `string` for date-time fields and `bigint` for bigint fields:
+
+```ts
+import { createClient } from '@hey-api/openapi-ts';
+import { createTRPCHeyApiTypeResolvers } from '@trpc/openapi/heyapi';
+
+await createClient({
+  input: './openapi.json',
+  output: './generated',
+  plugins: [
+    {
+      name: '@hey-api/typescript',
+      '~resolvers': createTRPCHeyApiTypeResolvers(),
+    },
+    {
+      name: '@hey-api/sdk',
+      operations: { strategy: 'single' },
+    },
+  ],
+});
+```
+
+### Runtime client with superjson transformer
+
+When the tRPC server uses `superjson`, the client must be configured with the same transformer:
+
+```ts
+// src/shared/transformer.ts
+import superjson from 'superjson';
+
+export const transformer = superjson;
+```
+
+```ts
+// src/server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import { transformer } from '../shared/transformer';
+
+const t = initTRPC.create({ transformer });
+export const router = t.router;
+export const publicProcedure = t.procedure;
+```
+
+```ts
+// src/client/index.ts
+import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
+import superjson from 'superjson';
+import { client } from './generated/client.gen';
+import { Sdk } from './generated/sdk.gen';
+
+configureTRPCHeyApiClient(client, {
+  baseUrl: 'http://localhost:3000',
+  transformer: superjson,
+});
+const sdk = new Sdk({ client });
+
+const event = await sdk.getEvent({
+  query: { input: { id: 'evt_1', at: new Date('2025-06-15T10:00:00Z') } },
+});
+// event.data.result.data.at is a Date object
+```
+
+### MongoDB EJSON transformer (cross-language)
+
+For non-TypeScript clients, EJSON provides a language-agnostic serialization format:
+
+```ts
+import type { TRPCDataTransformer } from '@trpc/server';
+import type { Document } from 'bson';
+import { EJSON } from 'bson';
+
+export const ejsonTransformer: TRPCDataTransformer = {
+  serialize: (value) => EJSON.serialize(value),
+  deserialize: (value) => EJSON.deserialize(value as Document),
+};
+```
+
+```ts
+import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
+import { client } from './generated/client.gen';
+import { ejsonTransformer } from './transformer';
+
+configureTRPCHeyApiClient(client, {
+  baseUrl: 'http://localhost:3000',
+  transformer: ejsonTransformer,
+});
+```
+
+### Response shape
+
+All tRPC HTTP responses follow the envelope format. Access data through `result.data`:
+
+```ts
+const listResult = await sdk.user.list();
+const users = listResult.data?.result.data; // the actual return value
+
+const createResult = await sdk.user.create({ body: { name: 'nick' } });
+const user = createResult.data?.result.data;
+// user.createdAt instanceof Date === true (when transformer is configured)
+```
+
+### Descriptions in the spec
+
+Zod `.describe()` calls and JSDoc comments on types, routers, and procedures become `description` fields in the generated OpenAPI spec. No annotations or decorators required.
+
+## Common Mistakes
+
+### Missing transformer config in HeyAPI client
+
+When the tRPC server uses `superjson` or another transformer, the generated HeyAPI client must also be configured with the same transformer via `configureTRPCHeyApiClient(client, { transformer })`. Without this, `Date`, `Map`, `Set`, and other non-JSON types will be silently wrong at runtime -- they arrive as raw serialized objects instead of their native types.
+
+Wrong:
+
+```ts
+configureTRPCHeyApiClient(client, {
+  baseUrl: 'http://localhost:3000',
+  // missing transformer -- Dates will be broken
+});
+```
+
+Right:
+
+```ts
+configureTRPCHeyApiClient(client, {
+  baseUrl: 'http://localhost:3000',
+  transformer: superjson, // must match server's transformer
+});
+```
+
+### Expecting subscriptions in OpenAPI spec
+
+Subscriptions are currently excluded from OpenAPI spec generation. The generator silently skips any procedure with `type: 'subscription'`. SSE subscription support is planned but not yet available.
+
+### Forgetting createTRPCHeyApiTypeResolvers when using a transformer
+
+Without the type resolvers plugin, HeyAPI generates `string` types for date-time fields instead of `Date`. The `createTRPCHeyApiTypeResolvers()` function maps `date`/`date-time` format to `Date` and `bigint` format to `bigint` in the generated TypeScript SDK.
+
+### Using the wrong export name
+
+The CLI defaults to `--export AppRouter` (the type). If your file exports the router value as `appRouter`, pass `-e appRouter`. If the export is not found, the error message lists all available exports from the file.
+
+## See Also
+
+- **server-setup** -- Required. Define routers and procedures before generating the spec.
+- **superjson** -- Transformer configuration for server and client. OpenAPI clients need matching transformer config.
+- **validators** -- Zod `.describe()` calls propagate into OpenAPI `description` fields.
+- Full working example: `examples/openapi-codegen/`