Skip to main content

​
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
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:
  1. Pin exact versions using the -E flag when installing
  2. Review migration notes before upgrading
  3. 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/[email protected] -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',
});

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us