Configuration Overview

OpenAPI TypeScript is configured using a configuration file in your project root. The CLI automatically detects and loads your configuration from supported file formats.

Configuration File

Create a configuration file in your project root using one of these formats:

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

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

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

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

const { defineConfig } = require('@hey-api/openapi-ts');

module.exports = defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: {
    path: './src/client',
  },
});

The defineConfig helper provides TypeScript autocomplete and type checking for your configuration.

Core Configuration Options

Every configuration requires at minimum an input and output:

string | object | array

required

Path to your OpenAPI specification. Can be a local file path, URL, or API registry shorthand.See Input Configuration for details.

string | object | array

required

Path to the output folder where generated files will be written.See Output Configuration for details.

array

default:"['@hey-api/typescript', '@hey-api/sdk']"

Plugins generate artifacts from your OpenAPI specification. By default, TypeScript types and SDK functions are generated.See Plugins Configuration for details.

object

Customize how the OpenAPI specification is parsed and transformed before plugins process it.See Parser Configuration for details.

Additional Options

string

Path to the config file. Set this if you don’t use the default config file name, or it’s not located in the project root.

boolean

default:false

Skip writing files to disk. Useful for testing configuration without generating output.

boolean

default:false

Show an interactive error reporting tool when the program crashes. Generally kept disabled.

string | object

default:"process.cwd()"

Configure logging behavior.

Show Logs Configuration

string

default:"process.cwd()"

The relative location of the logs folder.

string

default:"info"

The logging level to control verbosity. Options: trace, debug, info, warn, error, fatal, silent.

boolean

default:true

Whether error logs should be written to a file.

Multiple Configurations

You can export an array of configurations to generate multiple outputs from different inputs:

openapi-ts.config.ts

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

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

Async Configuration

The defineConfig helper supports async functions for dynamic configuration:

openapi-ts.config.ts

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

export default defineConfig(async () => {
  const apiUrl = await fetchApiUrl();
  
  return {
    input: apiUrl,
    output: {
      path: './src/client',
    },
  };
});

Next Steps

Input Configuration

Configure how OpenAPI specifications are loaded

Output Configuration

Control where and how files are generated

Parser Configuration

Transform and filter your OpenAPI specification

Plugins Configuration

Choose what artifacts to generate

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Configuration File

Core Configuration Options

Additional Options

Multiple Configurations

Async Configuration

Next Steps

Input Configuration

Output Configuration

Parser Configuration

Plugins Configuration

​Configuration File

​Core Configuration Options

​Additional Options

​Multiple Configurations

​Async Configuration

​Next Steps

Input Configuration

Output Configuration

Parser Configuration

Plugins Configuration

Configuration File

Core Configuration Options

Additional Options

Multiple Configurations

Async Configuration

Next Steps