TypeScript Plugin

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.

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.

boolean | string | object

default:"false"

Generate enums as JavaScript objects, TypeScript enums, or const enums.

Boolean
String
Object

{
  name: '@hey-api/typescript',
  enums: true, // Generates JavaScript objects
}

{
  name: '@hey-api/typescript',
  enums: 'typescript', // Options: 'javascript' | 'typescript' | 'typescript-const'
}

{
  name: '@hey-api/typescript',
  enums: {
    enabled: true,
    mode: 'javascript', // 'javascript' | 'typescript' | 'typescript-const'
    case: 'SCREAMING_SNAKE_CASE',
    constantsIgnoreNull: false, // Remove null values from enum objects
  },
}

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

// enums: 'javascript'
export const Status = {
  ACTIVE: 'active',
  INACTIVE: 'inactive',
  PENDING: 'pending',
} as const;

// enums: 'typescript'
export enum Status {
  ACTIVE = 'active',
  INACTIVE = 'inactive',
  PENDING = 'pending',
}

// enums: 'typescript-const'
export const enum Status {
  ACTIVE = 'active',
  INACTIVE = 'inactive',
  PENDING = 'pending',
}

`topType`

The top type to use for untyped or unspecified schema values.

'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.

string | function | object

default:"'{{name}}'"

Controls generation of shared types that can be referenced across requests and responses.

String Pattern
Function
Object

{
  name: '@hey-api/typescript',
  definitions: '{{name}}Schema',
}

{
  name: '@hey-api/typescript',
  definitions: (name) => `${name}Type`,
}

{
  name: '@hey-api/typescript',
  definitions: {
    name: '{{name}}Schema',
    case: 'camelCase',
  },
}

`requests`

Customize naming for request-specific types (body, query, path parameters, headers).

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.

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.

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.

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:

function

Called after the plugin generates types. Useful for post-processing.

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.

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Installation

Configuration

What It Generates

Configuration Options

`case`

`enums`

`topType`

`definitions`

`requests`

`responses`

`errors`

`webhooks`

Common Patterns

Custom Naming Convention

Generate JavaScript Enums

Custom Type Transformer

Plugin Hooks

Next Steps

SDK Plugin

Schemas Plugin

Transformers Plugin

HTTP Clients

​Installation

​Configuration

​What It Generates

​Configuration Options

​case

​enums

​topType

​definitions

​requests

​responses

​errors

​webhooks

​Common Patterns

​Custom Naming Convention

​Generate JavaScript Enums

​Custom Type Transformer

​Plugin Hooks

​Next Steps

SDK Plugin

Schemas Plugin

Transformers Plugin

HTTP Clients

Installation

Configuration

What It Generates

Configuration Options

`case`

`enums`

`topType`

`definitions`

`requests`

`responses`

`errors`

`webhooks`

Common Patterns

Custom Naming Convention

Generate JavaScript Enums

Custom Type Transformer

Plugin Hooks

Next Steps