Skip to main content
The @hey-api/typescript plugin is the foundation of OpenAPI TypeScript. It generates TypeScript types and interfaces from your OpenAPI specification, providing full type safety for your API.

​
Installation

The TypeScript plugin is included by default when you install @hey-api/openapi-ts: 
npm install @hey-api/openapi-ts --save-dev

​
Configuration

Add the plugin to your openapi-ts.config.ts: 
import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi.yaml',
  output: {
    path: './src/client',
  },
  plugins: [
    '@hey-api/typescript',
  ],
});

​
What It Generates

The TypeScript plugin generates a types.gen.ts file containing:
  • Schema types - TypeScript types for all schema definitions
  • Request types - Types for request bodies, query parameters, and headers
  • Response types - Types for response bodies and status codes
  • Error types - Types for error responses
  • Enum types - JavaScript objects, TypeScript enums, or union types
// types.gen.ts
export type User = {
  id: string;
  name: string;
  email: string;
  createdAt: string;
};

export type GetUsersData = {
  query?: {
    limit?: number;
    offset?: number;
  };
};

export type GetUsersResponse = {
  users: Array<User>;
  total: number;
};

export type GetUsersErrors = {
  404: { message: string };
  500: { message: string };
};

​
Configuration Options

​
case

Casing convention for generated type names.
​
case
string
default:"PascalCase"
Options: 'PascalCase', 'camelCase', 'snake_case', 'kebab-case'
{
  name: '@hey-api/typescript',
  case: 'camelCase',
}

​
enums

Control how enums are generated. By default, enums are emitted as TypeScript union types to preserve runtime-free output.
​
enums
boolean | string | object
default:"false"
Generate enums as JavaScript objects, TypeScript enums, or const enums.
{
  name: '@hey-api/typescript',
  enums: true, // Generates JavaScript objects
}

// enums: false
export type Status = 'active' | 'inactive' | 'pending';

​
topType

The top type to use for untyped or unspecified schema values.
​
topType
'unknown' | 'any'
default:"'unknown'"
  • 'unknown' - Safe top type, requires type narrowing before use
  • 'any' - Disables type checking, can be used anywhere
{
  name: '@hey-api/typescript',
  topType: 'any',
}

​
definitions

Customize naming for reusable schema definitions.
​
definitions
string | function | object
default:"'{{name}}'"
Controls generation of shared types that can be referenced across requests and responses.
{
  name: '@hey-api/typescript',
  definitions: '{{name}}Schema',
}

​
requests

Customize naming for request-specific types (body, query, path parameters, headers).
​
requests
string | function | object
default:"'{{name}}Data'"
Controls generation of types for request bodies, query parameters, path parameters, and headers.
{
  name: '@hey-api/typescript',
  requests: '{{name}}Request',
}

​
responses

Customize naming for response-specific types.
​
responses
string | function | object
default:"'{{name}}Responses'"
Controls generation of types for response bodies and status codes.
{
  name: '@hey-api/typescript',
  responses: {
    name: '{{name}}Responses', // Union of all response types
    response: '{{name}}Response', // Individual response type
    case: 'PascalCase',
  },
}

​
errors

Customize naming for error-specific types.
​
errors
string | function | object
default:"'{{name}}Errors'"
Controls generation of types for error response bodies and status codes.
{
  name: '@hey-api/typescript',
  errors: {
    name: '{{name}}Errors', // Union of all error types
    error: '{{name}}Error', // Individual error type
    case: 'PascalCase',
  },
}

​
webhooks

Customize naming for webhook-specific types.
​
webhooks
string | function | object
default:"'{{name}}WebhookRequest'"
Controls generation of types for webhook payloads and webhook requests.
{
  name: '@hey-api/typescript',
  webhooks: {
    name: '{{name}}WebhookRequest',
    payload: '{{name}}WebhookPayload',
    case: 'PascalCase',
  },
}

​
Common Patterns

​
Custom Naming Convention

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi.yaml',
  output: { path: './src/client' },
  plugins: [
    {
      name: '@hey-api/typescript',
      case: 'camelCase',
      requests: '{{name}}Input',
      responses: '{{name}}Output',
      errors: '{{name}}ErrorResponse',
    },
  ],
});

​
Generate JavaScript Enums

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi.yaml',
  output: { path: './src/client' },
  plugins: [
    {
      name: '@hey-api/typescript',
      enums: {
        enabled: true,
        mode: 'javascript',
        case: 'SCREAMING_SNAKE_CASE',
      },
    },
  ],
});

​
Custom Type Transformer

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi.yaml',
  output: { path: './src/client' },
  plugins: [
    {
      name: '@hey-api/typescript',
      definitions: (name) => {
        // Add 'I' prefix for interfaces
        return `I${name}`;
      },
    },
  ],
});

​
Plugin Hooks

The TypeScript plugin supports lifecycle hooks for advanced customization:
​
onAfter
function
Called after the plugin generates types. Useful for post-processing.
​
onBefore
function
Called before the plugin generates types. Useful for pre-processing.
{
  name: '@hey-api/typescript',
  onBefore: (context) => {
    console.log('Generating TypeScript types...');
  },
  onAfter: (context) => {
    console.log('TypeScript types generated!');
  },
}

​
Next Steps

SDK Plugin

Generate type-safe SDK functions for your API operations.

Schemas Plugin

Generate runtime JSON schemas for validation.

Transformers Plugin

Transform response data at runtime.

HTTP Clients

Choose an HTTP client for making requests.

Build docs developers (and LLMs) love

Get started for freeTalk to us