tRPC

https://trpc.io/docs
Admin
tRPC enables easy end-to-end typesafe APIs, simplifying development and improving developer...
Tokens:209,264
Snippets:1,769
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install @trpc/openapi

Source: https://trpc.io/docs/openapi

Install the @trpc/openapi package using pnpm.

```bash
pnpm add @trpc/openapi
Copy

```

--------------------------------

### Install SuperJSON

Source: https://trpc.io/docs/openapi

Install the SuperJSON package to use it as a data transformer.

```bash
pnpm add superjson
Copy

```

--------------------------------

### Install Dependencies for tRPC OpenAPI

Source: https://trpc.io/docs/openapi

Install the necessary packages for using tRPC with OpenAPI and Hey API.

```bash
pnpm add @trpc/openapi @hey-api/openapi-ts
Copy

```

--------------------------------

### Generate OpenAPI Spec with CLI

Source: https://trpc.io/docs/openapi

Use the `trpc-openapi` CLI command to generate the OpenAPI specification. This is the simplest way to get started.

```bash
pnpm exec trpc-openapi ./src/server/router.ts
```

--------------------------------

### Install tRPC Skills for AI Agents

Source: https://trpc.io/docs/openapi

Install tRPC skills for AI coding agents using npx to improve code generation.

```bash
npx @tanstack/intent@latest install
Copy

```

--------------------------------

### Install BSON for EJSON

Source: https://trpc.io/docs/openapi

Install the 'bson' package to use MongoDB Extended JSON (EJSON) as a data transformer.

```bash
pnpm add bson
Copy

```

--------------------------------

### Install ion-js for Amazon Ion

Source: https://trpc.io/docs/openapi

Install the 'ion-js' package if you plan to use Amazon Ion as a data transformer.

```bash
pnpm add ion-js
Copy

```

--------------------------------

### Configure tRPC Hey API Client (No Transformer)

Source: https://trpc.io/docs/openapi

Configure the generated Hey API client to work with tRPC endpoints. This setup handles request serialization, response parsing, and error deserialization.

```typescript
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 });
const result = await sdk.greeting({ query: { input: { name: 'World' } } });
const user = await sdk.user.create({ body: { name: 'Bob', age: 30 } });
Copy

```

--------------------------------

### Generate OpenAPI Client with Hey API CLI

Source: https://trpc.io/docs/openapi

Generate the OpenAPI client code using the Hey API CLI. This is for cases without a data transformer.

```bash
pnpm exec openapi-ts -i openapi.json -o ./generated
Copy

```

--------------------------------

### Generate OpenAPI Spec with CLI and Options

Source: https://trpc.io/docs/openapi

Customize the OpenAPI specification generation using CLI options such as output file, title, version, and server URL.

```bash
pnpm exec trpc-openapi ./src/server/router.ts -o api.json --title "My API" --version 1.0.0 --server-url https://api.example.com/trpc
```

--------------------------------

### Generate Complete Changelog with oasdiff

Source: https://trpc.io/docs/openapi

Use the `changelog` command to generate a comprehensive changelog detailing all changes between two OpenAPI specifications, including informational, warning, and error categories.

```sh
# Get a complete changelog including minor and breaking changes
$ oasdiff changelog packages/openapi/test/routers/superjsonRouter.openapi.json /tmp/superjsonRouter.openapi.next.json
3 changes: 2 error, 0 warning, 1 info
error [new-required-request-property] in API POST /createEvent
  added the new required request property 'location'
error [api-path-removed-without-deprecation] in API GET /getBigInt
  api path removed without deprecation
info [endpoint-added] in API GET /health
  endpoint added
```

--------------------------------

### Generate OpenAPI Client Programmatically with Type Resolvers

Source: https://trpc.io/docs/openapi

Generate the OpenAPI client code programmatically using Hey API's `createClient`. This method is recommended when using data transformers, as it allows for correct type emission.

```typescript
import { createClient } from '@hey-api/openapi-ts';
import { createTRPCHeyApiTypeResolvers } from '@trpc/openapi/heyapi';
const openApiJson = './path/to/openapi.json'
const outputDir = './generated'
await createClient({
  input: openApiJson,
  output: outputDir,
  plugins: [
    {
      name: '@hey-api/typescript',
      // Important: this ensures that your emitted types like Dates are correct
      '~resolvers': createTRPCHeyApiTypeResolvers(),
    },
    {
      name: '@hey-api/sdk',
      operations: { strategy: 'single' },
    },
  ],
});
Copy

```

--------------------------------

### Configure SuperJSON on tRPC Server

Source: https://trpc.io/docs/openapi

Initialize tRPC with SuperJSON as the data transformer on the server.

```typescript
import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
const t = initTRPC.create({ transformer: superjson });
Copy

```

--------------------------------

### Implement a Custom Data Transformer

Source: https://trpc.io/docs/openapi

Create a custom data transformer by implementing `serialize` and `deserialize` methods. This allows for custom encoding and decoding of rich types.

```typescript
import type { TRPCDataTransformer } from '@trpc/server';
const myTransformer: TRPCDataTransformer = {
  serialize: (value) => {
    /* encode rich types */
  },
  deserialize: (value) => {
    /* decode them back */
  },
};
Copy

```

--------------------------------

### Configure SuperJSON on OpenAPI Client

Source: https://trpc.io/docs/openapi

Configure the OpenAPI client with SuperJSON as the data transformer. Ensure the baseUrl is set correctly.

```typescript
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import superjson from 'superjson';
import { client } from './generated/client.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  transformer: superjson,
});
Copy

```

--------------------------------

### Configure tRPC Hey API Client (With Transformer)

Source: https://trpc.io/docs/openapi

Configure the generated Hey API client when your backend uses a data transformer like `superjson`. This ensures that non-JSON types are handled correctly during serialization and deserialization.

```typescript
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import superjson from 'superjson';
import { client } from './generated/client.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  // Important, this transformer must match your tRPC API's transformer:
  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 ✅
const created = await sdk.createEvent({
  body: { name: 'Conference', at: new Date('2025-09-01T09:00:00Z') },
});
Copy

```

--------------------------------

### Configure EJSON on OpenAPI Client

Source: https://trpc.io/docs/openapi

Configure the OpenAPI client with the custom EJSON transformer. Ensure the baseUrl is set correctly.

```typescript
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import { client } from './generated/client.gen';
import { ejsonTransformer } from './transformer';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  transformer: ejsonTransformer,
});
Copy

```

--------------------------------

### Create EJSON Transformer

Source: https://trpc.io/docs/openapi

Implement a tRPC data transformer using BSON's EJSON.serialize and EJSON.deserialize methods for cross-language support.

```typescript
import { EJSON } from 'bson';
import type { TRPCDataTransformer } from '@trpc/server';
export const ejsonTransformer: TRPCDataTransformer = {
  serialize: (value) => EJSON.serialize(value),
  deserialize: (value) => EJSON.deserialize(value as Document),
};
Copy

```

--------------------------------

### Detect Breaking Changes with oasdiff

Source: https://trpc.io/docs/openapi

Utilize the `breaking` command to specifically identify and list any breaking changes between two OpenAPI specifications. This helps in understanding the impact of API modifications on consumers.

```sh
# Get a list of breaking changes if any
$ oasdiff breaking packages/openapi/test/routers/superjsonRouter.openapi.json /tmp/superjsonRouter.openapi.next.json
2 changes: 2 error, 0 warning, 0 info
error [new-required-request-property] in API POST /createEvent
  added the new required request property 'location'
error [api-path-removed-without-deprecation] in API GET /getBigInt
  api path removed without deprecation
```

--------------------------------

### Generate OpenAPI Spec Programmatically

Source: https://trpc.io/docs/openapi

Generate the OpenAPI specification document programmatically within your TypeScript code using the `generateOpenAPIDocument` function.

```typescript
import { generateOpenAPIDocument } from '@trpc/openapi';
const doc = await generateOpenAPIDocument('./src/server/router.ts', {
  exportName: 'AppRouter',
  title: 'My API',
  version: '1.0.0',
  servers: [{ url: 'https://api.example.com/trpc' }],
});
```
Tokens:
Raw