Project setup

1. Copy the source/ directory into your project, for example at packages/openapi-ts/.

2. Add path aliases to your root tsconfig.json if you want to import from it as a package:

{
  "compilerOptions": {
    "paths": {
      "openapi-ts": ["./packages/openapi-ts/src/index.ts"]
    }
  }
}

3. Ensure your tsconfig.json targets at minimum "module": "NodeNext" or "ESNext" and "moduleResolution": "NodeNext" since the source uses ESM imports.

4. Install the required peer packages (see above).

5. To use the CLI directly from the copied source, wire a script in your root package.json:

{
  "scripts": {
    "generate": "node packages/openapi-ts/bin/run.js -i openapi.yaml -o src/client"
  }
}

6. For programmatic use, import createClient from packages/openapi-ts/src/index.ts (or via your path alias).

Public API

createClient

import { createClient } from 'openapi-ts';

const contexts = await createClient({
  input: 'https://example.com/openapi.yaml',
  output: './src/client',
  plugins: ['@hey-api/typescript', '@hey-api/sdk'],
});

The primary programmatic entry point. Accepts a configuration object describing one or more inputs and outputs, runs all configured plugins, and returns an array of generation context objects. Use this when integrating code generation into a build script or custom tooling rather than the CLI.

runCli

import { runCli } from 'openapi-ts/src/cli/index';

await runCli();

Parses process.argv using Commander, maps CLI flags to a config object, and calls createClient. Handles watch mode by keeping the process alive when --watch is active. Use this if you are wrapping the CLI in a custom bin script or test harness.

AngularCommonPlugin / defineConfig (Angular plugin)

import { defineConfig } from 'openapi-ts/src/plugins/@angular/common';
import type { AngularCommonPlugin } from 'openapi-ts/src/plugins/@angular/common';

const config: AngularCommonPlugin = defineConfig({
  // Angular-specific options
});

defineConfig constructs a validated Angular plugin config object. AngularCommonPlugin is the TypeScript type for the resolved config. Use these when you need Angular HttpClient-based service generation instead of the default fetch/axios clients.

resolveHttpRequests / resolveHttpRequestsStrategy

import {
  resolveHttpRequests,
  resolveHttpRequestsStrategy,
} from 'openapi-ts/src/plugins/@angular/common/httpRequests';
import type { HttpRequestsConfig, UserHttpRequestsConfig } from 'openapi-ts/src/plugins/@angular/common/httpRequests';

resolveHttpRequests converts user-supplied Angular HTTP request options into a fully-resolved HttpRequestsConfig. resolveHttpRequestsStrategy determines which request strategy (e.g., observable vs. promise) to apply. Use these when extending or customizing Angular code generation behavior in a plugin.

Working examples

Scenario - Generate a TypeScript client from a local OpenAPI file

A build script that reads a local YAML spec and writes typed SDK files to src/generated/.

import { createClient } from 'openapi-ts/src/createClient';

async function generate() {
  const contexts = await createClient({
    input: './openapi.yaml',
    output: {
      path: './src/generated',
      format: 'prettier',
      lint: 'eslint',
    },
    plugins: [
      '@hey-api/typescript',
      '@hey-api/sdk',
    ],
  });

  console.log(`Generated ${contexts.length} output(s)`);
}

generate().catch((err) => {
  console.error(err);
  process.exit(1);
});

Scenario - Run the CLI programmatically with watch mode

Embedding the CLI runner in a dev server startup so files regenerate on spec changes.

import { runCli } from 'openapi-ts/src/cli/index';

// Set argv so Commander picks up our flags
process.argv = [
  'node',
  'openapi-ts',
  '--input', './openapi.yaml',
  '--output', './src/client',
  '--watch', '2000',
  '--plugins', '@hey-api/typescript',
];

runCli().catch((err) => {
  console.error('CLI error:', err);
  process.exit(1);
});

Scenario - Use the Angular plugin for HttpClient-based service generation

Generate Angular services using the Angular common plugin config.

import { createClient } from 'openapi-ts/src/createClient';
import { defineConfig as defineAngularConfig } from 'openapi-ts/src/plugins/@angular/common';

async function generateAngularClient() {
  await createClient({
    input: 'https://petstore3.swagger.io/api/v3/openapi.json',
    output: './src/api',
    plugins: [
      '@hey-api/typescript',
      defineAngularConfig({
        // Angular-specific overrides go here
      }),
    ],
  });
}

generateAngularClient();

File walkthrough

• bin/run.js - Thin executable that bootstraps src/cli/index.ts via Node; the entry point for the openapi-ts CLI command.
• src/cli/index.ts - Defines the Commander program, maps CLI flags to config, and delegates to createClient; exports runCli.
• src/cli/adapter.ts - Converts raw CLI option objects into the typed config shape expected by createClient.
• src/cli/schema.ts - Zod or similar schema definitions for validating CLI input.
• src/config/ - Handles all lifecycle phases of configuration: expansion of shorthands (expand.ts), initialization of defaults (init.ts), plugin resolution (plugins.ts), output config (output/), and final validation (validate.ts).
• src/generate/client.ts - Orchestrates per-client generation: iterates plugins, invokes their handlers, and collects output.
• src/generate/output.ts - Writes generated files to disk, applies formatting/linting if configured.
• src/plugins/ - One subdirectory per plugin family; each plugin exposes config.ts, types.ts, and a plugin.ts handler.
• src/plugins/@angular/ - Angular HttpClient plugin with support for both request-based and resource-based APIs.
• src/plugins/@faker-js/ - Faker.js data mock generation from OpenAPI schemas.
• src/ts-compiler/ - Wraps the TypeScript compiler API for parsing and type-checking generated output.
• src/ts-dsl/ - Utility functions to programmatically construct TypeScript AST nodes without raw string templates.
• src/createClient.ts - Thin public wrapper that wires config resolution and generation together.
• src/generate.ts - Internal core that drives the full generation pipeline.
• src/index.ts - Public package entry: re-exports the API and applies module augmentations to @hey-api/codegen-core and @hey-api/shared.
• src/internal.ts - Internal helpers intentionally excluded from the public API surface.
• src/run.ts - Implements single-shot and watch-mode execution loops.

Common pitfalls and fixes

• ESM/CJS mismatch: The source uses import/export; ensure your consuming project has "type": "module" in package.json or transpiles via ts-node --esm. Fix: add "type": "module" or use tsx as the runner.
• Missing @hey-api/codegen-core module augmentation: If you import from src/index.ts and see type errors on ProjectRenderMeta or SymbolMeta, ensure @hey-api/codegen-core is installed and its types are on the TypeScript path.
• commander not found: The CLI depends on commander which is not bundled. Fix: npm install commander.
• Watch mode keeps process alive unexpectedly: createClient returns without exiting when any input has watch.enabled: true. Fix: check context[0]?.config.input.some(i => i.watch?.enabled) and call process.exit(0) manually if you do not want watch behavior.
• Output path not created: The generator does not create missing nested directories by default on all configurations. Fix: pre-create the output directory with fs.mkdirSync(outputPath, { recursive: true }) before calling createClient.
• Plugin order matters: Some plugins depend on @hey-api/typescript running first to register type symbols. Fix: always place @hey-api/typescript before SDK or schema plugins in the plugins array.

Vibe-coding prompt template

I have copied the openapi-ts source from the AVCP block into `packages/openapi-ts/` in my project.
I also have USAGE.md open as context.

The upstream package is `user@example.com` and the core source root is `packages/openapi-ts`.

Please help me integrate this into my project step by step:

1. Read USAGE.md and the file excerpts from `packages/openapi-ts/src/index.ts`, `src/cli/index.ts`,
   and the Angular plugin files to understand the real exported API.
2. Add the required dependencies (`@hey-api/codegen-core`, `@hey-api/shared`, `commander`) to my
   root `package.json` and install them.
3. Configure `tsconfig.json` path aliases so I can import from `openapi-ts` pointing at
   `packages/openapi-ts/src/index.ts`.
4. Create a `scripts/generate.ts` file that calls `createClient` with my OpenAPI spec at
   `./openapi.yaml` and outputs to `./src/generated`, using the `@hey-api/typescript` and
   `@hey-api/sdk` plugins.
5. Add a `"generate"` npm script that runs `scripts/generate.ts` via `tsx`.
6. If I need Angular services, show me how to swap in the Angular common plugin using `defineConfig`
   from `packages/openapi-ts/src/plugins/@angular/common/index.ts`.
7. Warn me about any ESM/CJS or watch-mode pitfalls from USAGE.md that apply to my setup.

Only use exports that are visible in the source file excerpts and USAGE.md. Do not invent APIs.

License and credit

See source/LICENSE.md for the full license text. This block is derived from the user@example.com upstream package. Original project: hey-api/openapi-ts.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Orval OpenAPI TypeScript Client Code Generator

Automation, Utilities & Developer Tools

Free