Installation

Package Manager Installation

Install @hey-api/openapi-ts as a dev dependency using your preferred package manager:

npm install @hey-api/openapi-ts -D -E

pnpm add @hey-api/openapi-ts -D -E

yarn add @hey-api/openapi-ts -D -E

bun add @hey-api/openapi-ts -D -E

The -E flag (or --save-exact) pins the exact version. This is recommended due to the package being in initial development (see Versioning).

Requirements

OpenAPI TypeScript has minimal requirements:

Node.js: >=20.19.0
TypeScript: >=5.5.3 (peer dependency)

You can verify your Node.js version:

node --version

If you need to upgrade Node.js, we recommend using nvm or fnm.

Versioning

This package is in initial development (v0.x.x). Breaking changes may occur between minor versions.

To safely upgrade:

Pin exact versions using the -E flag when installing
Review migration notes before upgrading
Test thoroughly after upgrading

Migration Notes

We publish detailed migration notes for every breaking release. You might not be impacted by a breaking change if you don’t use the affected features. Check the migration guide when upgrading:

# Check current version
npm list @hey-api/openapi-ts

# Review migration notes at:
# https://heyapi.dev/openapi-ts/migrating

# Upgrade to specific version
npm install @hey-api/openapi-ts@0.93.1 -D -E

Adding to package.json Scripts

After installation, add a script to your package.json to make the CLI easily accessible:

package.json

{
  "scripts": {
    "openapi-ts": "openapi-ts"
  }
}

Now you can run the generator with:

npm run openapi-ts

You can customize the script name to match your workflow, such as "generate:client" or "codegen".

Basic Setup

After installation, create a configuration file to define your code generation settings.

Configuration File

OpenAPI TypeScript supports multiple configuration file formats. The most common is openapi-ts.config.ts:

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

export default defineConfig({
  input: 'path/to/openapi.json',
  output: 'src/client',
});

/** @type {import('@hey-api/openapi-ts').UserConfig} */
module.exports = {
  input: 'path/to/openapi.json',
  output: 'src/client',
};

/** @type {import('@hey-api/openapi-ts').UserConfig} */
export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
};

Running the Generator

With the configuration file in place, run the generator:

npm run openapi-ts

The generator will read your configuration and create the output files in the specified directory.

Programmatic Usage

You can also use OpenAPI TypeScript programmatically in Node.js:

script.ts

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

await createClient({
  input: 'path/to/openapi.json',
  output: 'src/client',
});

Run your script:

node --loader tsx script.ts

This is useful for:

Custom build pipelines
Dynamic configuration
Integration with other tools
CI/CD workflows

Verification

Verify the installation by checking the version:

npx openapi-ts --version

You should see output like:

0.93.1

Project Structure

Here’s a typical project structure after installation:

my-project/
├── node_modules/
├── src/
│   ├── client/              # Generated by OpenAPI TypeScript
│   │   ├── sdk.gen.ts
│   │   ├── types.gen.ts
│   │   ├── schemas.gen.ts
│   │   └── client.ts
│   └── index.ts             # Your application code
├── openapi-ts.config.ts     # Configuration file
├── package.json
└── tsconfig.json

Add the output directory (e.g., src/client/) to your .gitignore if you regenerate it as part of your build process. Otherwise, commit it if other developers need the generated code.

TypeScript Configuration

Ensure your tsconfig.json is configured for ESM modules:

tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2022",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"]
}

Watch Mode

During development, you can enable watch mode to automatically regenerate code when your OpenAPI specification changes:

npm run openapi-ts -- -w

Or configure it in your config file:

openapi-ts.config.ts

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

export default defineConfig({
  input: 'path/to/openapi.json',
  output: 'src/client',
  watch: process.env.NODE_ENV === 'development',
});

Multiple Configurations

You can generate multiple clients from different OpenAPI specifications:

openapi-ts.config.ts

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

export default defineConfig([
  {
    input: 'https://api.example.com/v1/openapi.json',
    output: 'src/client/v1',
  },
  {
    input: 'https://api.example.com/v2/openapi.json',
    output: 'src/client/v2',
  },
]);

Next Steps

Configuration

Learn about all configuration options

Quick Start

Generate your first client

Plugins

Explore available plugins

HTTP Clients

Choose your HTTP client

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Package Manager Installation

Requirements

Versioning

Migration Notes

Adding to package.json Scripts

Basic Setup

Configuration File

Running the Generator

Programmatic Usage

Verification

Project Structure

TypeScript Configuration

Watch Mode

Multiple Configurations

Next Steps

Configuration

Quick Start

Plugins

HTTP Clients

​Package Manager Installation

​Requirements

​Versioning

​Migration Notes

​Adding to package.json Scripts

​Basic Setup

​Configuration File

​Running the Generator

​Programmatic Usage

​Verification

​Project Structure

​TypeScript Configuration

​Watch Mode

​Multiple Configurations

​Next Steps

Configuration

Quick Start

Plugins

HTTP Clients

Package Manager Installation

Requirements

Versioning

Migration Notes

Adding to package.json Scripts

Basic Setup

Configuration File

Running the Generator

Programmatic Usage

Verification

Project Structure

TypeScript Configuration

Watch Mode

Multiple Configurations

Next Steps