TypeScript

TypeScript interfaces are located in the types.gen.ts file. This is the only file that does not impact your bundle size and runtime performance. It will get discarded during build time, unless you configured to emit runtime enums.

Installation

In your configuration, add @hey-api/typescript to your plugins and you’ll be ready to generate TypeScript artifacts. 🎉

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@hey-api/typescript',
  ],
};

Note

The @hey-api/typescript plugin might be implicitly added to your plugins if another plugin depends on it.

Output

The TypeScript plugin will generate the following artifacts, depending on the input specification.

Requests

A single request type is generated for each endpoint. It may contain a request body, parameters, and headers.

types.gen.ts

export type AddPetData = {
  body: {
    id?: number;
    name: string;
  };
  path?: never;
  query?: never;
  url: '/pets';
};

You can customize the naming and casing pattern for requests types using the .name and .case options.

Responses

A single type is generated for all endpoint’s responses.

types.gen.ts

export type AddPetResponses = {
  200: {
    id?: number;
    name: string;
  };
};

export type AddPetResponse = AddPetResponses[keyof AddPetResponses];

You can customize the naming and casing pattern for responses types using the .name and .case options.

Definitions

A type is generated for every reusable definition from your input.

types.gen.ts

export type Pet = {
  id?: number;
  name: string;
};

You can customize the naming and casing pattern for definitions types using the .name and .case options.

Enums

By default, @hey-api/typescript will emit enums only as types. You may want to generate runtime artifacts. A good use case is iterating through possible field values without manually typing arrays. To emit runtime enums, set enums to a valid option.

disabled

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      enums: false, // default
      name: '@hey-api/typescript',
    },
  ],
};

javascript

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      enums: 'javascript',
      name: '@hey-api/typescript',
    },
  ],
};

typescript

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      enums: 'typescript',
      name: '@hey-api/typescript',
    },
  ],
};

We recommend exporting enums as plain JavaScript objects. TypeScript enums are not a type-level extension of JavaScript and pose typing challenges.

Comments

By default, @hey-api/typescript will include comments in the generated code based on descriptions from your OpenAPI specification. If you want to reduce the size of your generated files or prefer cleaner output, you can disable comments.

enabled

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      comments: true, // default
      name: '@hey-api/typescript',
    },
  ],
};

disabled

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      comments: false,
      name: '@hey-api/typescript',
    },
  ],
};

Resolvers

You can further customize this plugin’s behavior using resolvers.

API

You can view the complete list of options in the UserConfig interface.

Examples

You can view live examples on StackBlitz or on GitHub.