Files
skills/public/hanzo-trpc-openapi.md

9.5 KiB

Hanzo tRPC OpenAPI - Generate OpenAPI Specs from tRPC Routers

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-platform.md, hanzo/hanzo-openapi.md

Overview

@hanzo/trpc-openapi is a TypeScript library that generates OpenAPI 3.x documents from tRPC v11 routers and provides HTTP adapters to serve tRPC procedures as REST endpoints. Published on npm as @hanzo/trpc-openapi. This is a maintained fork of the abandoned trpc-to-openapi project with Hanzo-specific enhancements.

Why @hanzo/trpc-openapi?

  • tRPC + REST: Expose tRPC procedures as standard REST endpoints without duplicating code
  • OpenAPI doc generation: Auto-generate Swagger/OpenAPI specs from your tRPC router definitions
  • Multiple adapters: Express, Fastify, Next.js (pages + app router), Nuxt, Koa, Fetch API, standalone Node HTTP
  • Zod v4 native: Built for Zod v4 with zod-openapi v5 integration
  • Optional meta: Procedures without .meta({ openapi: ... }) are still exposed with sensible defaults (method from procedure type, path from procedure path)

Tech Stack

  • Language: TypeScript 5.8
  • Runtime: Node.js
  • Package Manager: pnpm
  • tRPC: v11.1.0+ (peer dependency)
  • Zod: v4.x (peer dependency)
  • OpenAPI: openapi3-ts v4.4.0, zod-openapi v5.x (peer dependency)
  • Testing: Jest 29 + ts-jest
  • Linting: ESLint + Prettier
  • Build: TypeScript compiler (dual CJS + ESM output)

OSS Base

Fork of trpc-to-openapi. Hanzo-specific additions:

  • Optional input/output parameters are required by default in generated docs
  • .meta is optional for all procedures (auto-generates defaults)
  • override flag: use only provided openapi object, no defaults merged
  • additional flag: merge provided openapi on top of defaults

Repo: github.com/hanzoai/trpc-openapi

When to use

  • Exposing tRPC procedures as REST/OpenAPI endpoints
  • Generating OpenAPI/Swagger documentation from tRPC routers
  • Building APIs that need both tRPC and REST access
  • Incremental migration between REST and tRPC
  • Auto-documenting Hanzo platform tRPC services

Hard requirements

  1. @trpc/server ^11.1.0
  2. zod ^4.0.0 (Zod v4, not v3)
  3. zod-openapi ^5.0.1
  4. Node.js 22+ (based on @types/node ^22)

Quick reference

Item Value
npm Package @hanzo/trpc-openapi
Version 0.0.17
Repo github.com/hanzoai/trpc-openapi
Branch main
License MIT
tRPC Version ^11.1.0 (peer dep)
Zod Version ^4.0.0 (peer dep)
Build pnpm build (runs tests first)
Test pnpm test
Exports CJS (dist/cjs/) + ESM (dist/esm/)

One-file quickstart

Install

pnpm add @hanzo/trpc-openapi
# peer deps
pnpm add @trpc/server zod zod-openapi

Define a tRPC router with OpenAPI metadata

import { initTRPC } from '@trpc/server';
import { z } from 'zod';
import { OpenApiMeta, generateOpenApiDocument, createOpenApiExpressMiddleware } from '@hanzo/trpc-openapi';
import express from 'express';

// 1. Create tRPC instance with OpenApiMeta
const t = initTRPC.meta<OpenApiMeta>().create();

// 2. Define router with openapi metadata
const appRouter = t.router({
 getUser: t.procedure
 .meta({ openapi: { method: 'GET', path: '/users/{id}' } })
 .input(z.object({ id: z.string() }))
 .output(z.object({ id: z.string(), name: z.string() }))
 .query(({ input }) => ({ id: input.id, name: 'Hanzo User' })),

 createUser: t.procedure
 .meta({ openapi: { method: 'POST', path: '/users', protect: true } })
 .input(z.object({ name: z.string(), email: z.string().email() }))
 .output(z.object({ id: z.string(), name: z.string() }))
 .mutation(({ input }) => ({ id: 'usr_new', name: input.name })),
});

// 3. Generate OpenAPI document
const openApiDoc = generateOpenApiDocument(appRouter, {
 title: 'My API',
 version: '1.0.0',
 baseUrl: 'http://localhost:3000',
});

// 4. Serve REST endpoints
const app = express();
app.get('/openapi.json', (req, res) => res.json(openApiDoc));
app.use('/api', createOpenApiExpressMiddleware({ router: appRouter }));
app.listen(3000);

Core Concepts

Architecture

┌──────────────────────┐
│ tRPC Router │
│ (procedures + meta) │
└──────┬───────────────┘
 │
 ┌────▼────────────────────┐
 │ generateOpenApiDocument │──── OpenAPI 3.x JSON
 └────┬────────────────────┘
 │
 ┌────▼────────────────────┐
 │ HTTP Adapter │──── REST endpoints
 │ (Express/Fastify/Next) │ GET /users/{id}
 └─────────────────────────┘ POST /users

Adapters

Adapter Import Handler Factory
Express @hanzo/trpc-openapi createOpenApiExpressMiddleware
Fastify @hanzo/trpc-openapi fastifyTRPCOpenApiPlugin
Next.js Pages @hanzo/trpc-openapi createOpenApiNextHandler
Next.js App Router @hanzo/trpc-openapi createOpenApiFetchHandler
Nuxt @hanzo/trpc-openapi createOpenApiNuxtHandler
Koa @hanzo/trpc-openapi createOpenApiKoaMiddleware
Fetch @hanzo/trpc-openapi createOpenApiFetchHandler
Node HTTP @hanzo/trpc-openapi createOpenApiHttpHandler
Standalone @hanzo/trpc-openapi createOpenApiHttpHandler (with http.createServer)

OpenApiMeta Fields

Field Type Default Description
method GET|POST|PATCH|PUT|DELETE (from proc type) HTTP method
path /${string} (from proc path) URL path with {param} placeholders
enabled boolean true Include in OpenAPI doc and adapters
protect boolean true Require Authorization header
override boolean false Use only provided openapi object (no defaults)
additional boolean false Merge provided openapi on top of defaults
tags string[] -- Grouping tags
summary string -- Short description
description string -- Verbose description
deprecated boolean false Mark as deprecated
contentTypes string[] ['application/json'] Accepted content types
requestHeaders ZodObject -- Custom request headers schema
responseHeaders ZodObject -- Custom response headers schema
errorResponses number[]|Record<number,string> -- Error response codes

Input Handling

  • GET/DELETE: Input from URL query parameters (auto-coerced to number, boolean, bigint, date)
  • POST/PATCH/PUT: Input from JSON request body
  • Path parameters: Defined as {paramName} in the path, must exist in input schema as string, number, bigint, or date

Filtering Procedures

const doc = generateOpenApiDocument<{ isPublic: boolean }>(appRouter, {
 title: 'API',
 version: '1.0.0',
 baseUrl: 'http://localhost:3000',
 filter: ({ metadata }) => metadata.isPublic === true,
});

Directory structure

trpc-openapi/
├── src/
│ ├── index.ts # Re-exports everything
│ ├── types.ts # OpenApiMeta, OpenApiMethod, response types
│ ├── generator/
│ │ ├── index.ts # generateOpenApiDocument()
│ │ ├── paths.ts # OpenAPI path generation
│ │ └── schema.ts # Zod-to-OpenAPI schema conversion
│ ├── adapters/
│ │ ├── express.ts # Express middleware
│ │ ├── fastify.ts # Fastify plugin
│ │ ├── next.ts # Next.js handler (pages + app)
│ │ ├── nuxt.ts # Nuxt handler
│ │ ├── koa.ts # Koa middleware
│ │ ├── fetch.ts # Fetch API handler
│ │ ├── standalone.ts # Standalone Node HTTP
│ │ └── node-http/ # Core Node HTTP handler
│ └── utils/ # Internal utilities
├── test/
│ ├── generator.test.ts # 115KB of generator tests
│ └── adapters/ # Adapter-specific tests
├── examples/
│ ├── with-express/
│ ├── with-fastify/
│ ├── with-nextjs/
│ ├── with-nextjs-appdir/
│ └── with-nuxtjs/
├── dist/
│ ├── cjs/ # CommonJS build output
│ └── esm/ # ESM build output
├── package.json # @hanzo/trpc-openapi v0.0.17
├── tsconfig.json
└── jest.config.ts

Troubleshooting

Issue Cause Solution
zod is not a function Using Zod v3 instead of v4 Upgrade to zod ^4.0.0
Procedures missing from OpenAPI doc enabled: false in meta Remove or set enabled: true
Query params not parsed Complex types in GET input Use z.preprocess() for objects/arrays in query params
404 on REST endpoint Path mismatch Ensure meta.openapi.path matches exactly, paths are case-insensitive
Auth not working protect: true but no createContext Implement createContext to extract Authorization header
Type error with meta tRPC not configured with OpenApiMeta Use initTRPC.meta<OpenApiMeta>().create()
  • hanzo/hanzo-platform.md - PaaS platform (uses tRPC + this library)
  • hanzo/hanzo-openapi.md - OpenAPI specification patterns
  • hanzo/hanzo-llm-gateway.md - LLM gateway API

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: trpc, openapi, swagger, rest, api Prerequisites: TypeScript, tRPC v11, Zod v4