Contributing to OpenAPI TypeScript

OpenAPI TypeScript is building an OpenAPI to TypeScript code generator ecosystem. It’s trusted by thousands of companies – from YC startups to Fortune 500 enterprises – and powers products used by millions worldwide, including Vercel, OpenCode, and PayPal. We welcome contributors of all backgrounds and experience levels. Whether you’re fixing a typo or building a new feature, your input matters.

New to open source? Check out the Open Source Guide or First Contributions for helpful information on contributing to open source projects.

Ways to Contribute

There are many ways to contribute to OpenAPI TypeScript. Most of them don’t involve writing any code!

Read the documentation

Start with our guides and documentation. If you find anything broken or confusing, you can suggest improvements by opening an issue or pull request.

Browse open issues

Help others by providing workarounds, asking for clarification, triaging, or suggesting labels on open issues. If you see something you’d like to work on, consider opening a pull request.

Participate in discussions

Ask or answer questions, provide feedback, or suggest new ideas. Every idea is welcome, no matter how big or small.

Engage on social media

Help others discover OpenAPI TypeScript by engaging with our posts on LinkedIn, Bluesky, or X. Share your experiences in your communities.

Development Setup

Prerequisites

You should have a working knowledge of:

Git
Node.js (>=20.19.0)
pnpm (10.28.2)

Quick Start

# Clone the repository
git clone https://github.com/hey-api/openapi-ts.git
cd openapi-ts

# Install dependencies
pnpm install

# Build packages
pnpm build --filter="@hey-api/**"

# Run tests
pnpm test

Do not cancel build commands - they take significant time:

pnpm install: ~1m 20s
pnpm build --filter="@hey-api/**": ~2m 15s
pnpm test: ~1m 5s

Development Commands

# Watch mode for openapi-ts (runs from dev/)
pnpm dev:ts

# Test specific package
pnpm tt -- @hey-api/openapi-ts

# Test watch mode
pnpm tw -- @hey-api/openapi-ts

# Update test snapshots
pnpm tu -- @hey-api/openapi-ts

# Type check
pnpm typecheck

# Lint and format
pnpm lint:fix

Repository Structure

The project is a monorepo built with pnpm workspaces and Turbo:

packages/
  openapi-ts/          # Main CLI tool and library
  openapi-python/      # Python DSL generation
  codegen-core/        # Core code generation utilities
  shared/              # Cross-package utilities
  types/               # Shared type definitions
  custom-client/       # Custom HTTP client implementations
  nuxt/                # Nuxt.js integration
  vite-plugin/         # Vite plugin
examples/              # 16+ framework-specific examples
docs/                  # VitePress documentation site
specs/                 # OpenAPI test specifications

Code Conventions

Our pre-commit hooks automatically format and lint your code, but it’s good to know the conventions:

ESM modules only (.mts/.mjs extensions in builds)
UTF-8, LF line endings, 2-space indentation
Single quotes (enforced by oxfmt)
Imports sorted by eslint-plugin-simple-import-sort
Object/interface keys sorted alphabetically
Destructured keys sorted alphabetically

Tooling

Package manager: pnpm 10.28.2 (strict engine, exact versions)
Node: >=20.19.0
Build: Turbo 2.8.0 + tsdown + Rollup
Language: TypeScript 5.9.3, ESM only
Formatter: oxfmt 0.27.0
Linter: ESLint 9 flat config
Tests: Vitest 3.2.4
Pre-commit: Husky + lint-staged
Releases: Changesets

Pull Request Guidelines

Your pull request must:

Address a single issue

Focus on one issue or feature per pull request to make reviews easier.

Contain clean history

Use small, incremental, logically separate commits with no merge commits.

Use clear commit messages

Follow Conventional Commits format:

feat: for new features
fix: for bug fixes
chore: for maintenance
docs: for documentation
refactor: for code refactoring

Be mergeable

Ensure your branch can be merged automatically without conflicts.

Pre-commit Checklist

Run these commands before committing (Husky runs format + lint automatically):

pnpm lint:fix       # Auto-fix formatting and linting
pnpm typecheck      # Type check
pnpm test           # Run tests

Some linting warnings in .gen/snapshots/ directories are expected for generated code.

Working with Examples

The examples folder contains integration examples that demonstrate how to use @hey-api/openapi-ts with different frameworks.

Generating Example Code

When you make changes that affect code generation:

# Build packages first
pnpm build --filter="@hey-api/**"

# Regenerate all examples
pnpm examples:generate

# Verify examples are in sync
pnpm examples:check

Think of generated example code as snapshot tests - they should always reflect the current state of the code generator.

Need Help?

If you need guidance, help with technical writing, or want to bring a feature idea to life:

Tag @mrlubos on GitHub
Open a discussion
Provide enough relevant information, and we’ll do our best to assist you

We’re excited to see what you’ll contribute!

​Contributing to OpenAPI TypeScript

​Ways to Contribute

​Development Setup

​Prerequisites

​Quick Start

​Development Commands

​Repository Structure

​Code Conventions

​Tooling

​Pull Request Guidelines

​Pre-commit Checklist

​Working with Examples

​Generating Example Code

​Need Help?

Contributing to OpenAPI TypeScript

Ways to Contribute

Development Setup

Prerequisites

Quick Start

Development Commands

Repository Structure

Code Conventions

Tooling

Pull Request Guidelines

Pre-commit Checklist

Working with Examples

Generating Example Code

Need Help?