mokkenstorm.dev / openapi-ts
fork of hey-api/openapi-ts because I need some additional things
fork atom
openapi-ts / .github / copilot-instructions.md
at feat/skip-token 6.3 kB view raw view code
Lubos test: print
77464698

Hey API OpenAPI TypeScript Codegen#

OpenAPI TypeScript is a CLI tool and library for generating TypeScript clients, SDKs, validators, and schemas from OpenAPI specifications. This is a monorepo built with pnpm workspaces, Turbo build orchestration, and TypeScript.

ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively#

Prerequisites and Setup#

  • Install Node.js (see .nvmrc for recommended version)
  • Install pnpm globally: npm install -g pnpm@10.15.1
  • Clone the repository and run setup commands

Bootstrap, Build, and Test#

# Install dependencies (takes ~1m 20s)
pnpm install

# Build packages only (NEVER CANCEL - takes ~2m 15s - set timeout to 180+ seconds)
pnpm build --filter="@hey-api/**"

# Build all including examples (NEVER CANCEL - takes ~5+ minutes - set timeout to 360+ seconds)
pnpm build

# Run tests (takes ~1m 5s - set timeout to 120+ seconds)
# NOTE: Some network-dependent tests may fail in sandboxed environments
pnpm test

# Run linting (takes ~35s)
pnpm lint

# Run type checking (NEVER CANCEL - takes ~1m 20s - set timeout to 120+ seconds)
pnpm typecheck

# Format code (takes ~35s)
pnpm format

Development Workflow#

# Start development mode for main package (watches for changes)
pnpm --filter @hey-api/openapi-ts dev

# Start development server for examples (e.g., fetch example)
pnpm --filter @example/openapi-ts-fetch dev
# Server starts on http://localhost:5173/

# Run CLI tool directly
node packages/openapi-ts/dist/run.js --help
# or after building
npx @hey-api/openapi-ts --help

Build and Test Details#

CRITICAL BUILD TIMING#

  • NEVER CANCEL BUILD COMMANDS - They may take 2-5+ minutes
  • pnpm build --filter="@hey-api/**": ~2m 15s (packages only)
  • pnpm build: ~5+ minutes (includes docs and examples)
  • pnpm install: ~1m 20s
  • pnpm test: ~1m 5s
  • pnpm typecheck: ~1m 20s
  • pnpm lint: ~35s
  • pnpm format: ~35s

Build Issues and Workarounds#

  • Docs build may fail due to pnpm version mismatch in VitePress - this is expected in some environments
  • Use pnpm build --filter="@hey-api/**" to build packages without docs
  • Some tests may fail in sandboxed environments due to network restrictions (OpenAPI spec downloads)
  • Generated test files in packages/openapi-ts-tests/ contain auto-generated snapshots that may have linting warnings - this is expected
  • Linting issues in .gen/snapshots/ directories are expected for generated code

Validation#

Manual Testing Scenarios#

After making changes, ALWAYS validate with these scenarios:

  1. CLI Functionality Test:

    # Test CLI help
node packages/openapi-ts/dist/run.js --help

# Test CLI version
node packages/openapi-ts/dist/run.js --version

# Test basic code generation with a simple OpenAPI spec
# Create a minimal test spec and generate client code
node packages/openapi-ts/dist/run.js -i path/to/spec.json -o ./test-output --plugins "@hey-api/client-fetch" "@hey-api/typescript"

  2. Example Application Test:

    # Start fetch example and verify it loads
pnpm --filter @example/openapi-ts-fetch dev
# Should start on http://localhost:5173/

  3. Development Mode Test:

    # Start dev mode and make a small change to verify rebuilding
pnpm --filter @hey-api/openapi-ts dev

Pre-commit Validation#

ALWAYS run these commands before committing or the CI will fail:

# Use lint:fix to auto-fix issues (some warnings in generated test files are expected)
pnpm lint:fix

# Run typecheck (can target specific packages with --filter)
pnpm typecheck

# Run tests (some network tests may fail in sandboxed environments)
pnpm test

NOTE: Some linting warnings in generated test snapshot files (.gen/snapshots/) are expected and should be ignored. The lint:fix command will resolve actual source code issues.

Repository Structure#

Key Packages#

  • packages/openapi-ts/ - Main CLI tool and library
  • packages/codegen-core/ - Core code generation utilities
  • packages/custom-client/ - Custom HTTP client implementations
  • packages/nuxt/ - Nuxt.js integration
  • packages/vite-plugin/ - Vite plugin

Examples#

  • examples/openapi-ts-fetch/ - Fetch client example (React + Vite)
  • examples/openapi-ts-angular/ - Angular client example
  • examples/openapi-ts-tanstack-react-query/ - TanStack React Query integration
  • examples/openapi-ts-vue/ - Vue.js integration
  • Plus many more framework-specific examples

Configuration Files#

  • pnpm-workspace.yaml - Workspace configuration
  • turbo.json - Turbo build configuration
  • package.json - Root package with workspace scripts
  • .nvmrc - Node.js version specification

Common Tasks#

Working with the Main Package#

# Install deps for main package
pnpm --filter @hey-api/openapi-ts install

# Build main package only
pnpm --filter @hey-api/openapi-ts build

# Test main package only
pnpm --filter @hey-api/openapi-ts test

# Start dev mode for main package
pnpm --filter @hey-api/openapi-ts dev

Working with Examples#

# List all example packages
ls examples/

# Run specific example
pnpm --filter @example/openapi-ts-fetch dev

# Build all examples
pnpm build --filter="@example/**"

Debugging and Troubleshooting#

  • Check turbo.json for task dependencies and configuration
  • Use pnpm list to see installed packages
  • Use pnpm why <package> to understand dependency chains
  • Check individual package package.json files for available scripts

CI/CD Pipeline#

The repository uses GitHub Actions (.github/workflows/ci.yml):

  • Tests on multiple Node.js versions
  • Tests on multiple OS (macOS, Ubuntu, Windows)
  • Runs build, lint, typecheck, and test commands
  • Publishes preview packages on PRs

Performance Expectations#

  • Cold install: ~1m 20s
  • Cold build: ~2-5m depending on scope
  • Incremental builds: ~30s in dev mode
  • Test suite: ~1m 5s
  • Linting: ~35s
  • Type checking: ~1m 20s

Remember: This is a complex monorepo with many dependencies. Be patient with build times and always use appropriate timeouts for long-running commands.