mokkenstorm.dev
fork of hey-api/openapi-ts because I need some additional things
1# Hey API OpenAPI TypeScript Codegen
2
3OpenAPI 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.
4
5**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.**
6
7## Working Effectively
8
9### Prerequisites and Setup
10
11- Install Node.js (see `.nvmrc` for recommended version)
12- Install pnpm globally: `npm install -g pnpm@10.15.1`
13- Clone the repository and run setup commands
14
15### Bootstrap, Build, and Test
16
17```bash
18# Install dependencies (takes ~1m 20s)
19pnpm install
20
21# Build packages only (NEVER CANCEL - takes ~2m 15s - set timeout to 180+ seconds)
22pnpm build --filter="@hey-api/**"
23
24# Build all including examples (NEVER CANCEL - takes ~5+ minutes - set timeout to 360+ seconds)
25pnpm build
26
27# Run tests (takes ~1m 5s - set timeout to 120+ seconds)
28# NOTE: Some network-dependent tests may fail in sandboxed environments
29pnpm test
30
31# Run linting (takes ~35s)
32pnpm lint
33
34# Run type checking (NEVER CANCEL - takes ~1m 20s - set timeout to 120+ seconds)
35pnpm typecheck
36
37# Format code (takes ~35s)
38pnpm format
39```
40
41### Development Workflow
42
43```bash
44# Start development mode for main package (watches for changes)
45pnpm --filter @hey-api/openapi-ts dev
46
47# Start development server for examples (e.g., fetch example)
48pnpm --filter @example/openapi-ts-fetch dev
49# Server starts on http://localhost:5173/
50
51# Run CLI tool directly
52node packages/openapi-ts/dist/run.js --help
53# or after building
54npx @hey-api/openapi-ts --help
55```
56
57## Build and Test Details
58
59### **CRITICAL BUILD TIMING**
60
61- **NEVER CANCEL BUILD COMMANDS** - They may take 2-5+ minutes
62- `pnpm build --filter="@hey-api/**"`: ~2m 15s (packages only)
63- `pnpm build`: ~5+ minutes (includes docs and examples)
64- `pnpm install`: ~1m 20s
65- `pnpm test`: ~1m 5s
66- `pnpm typecheck`: ~1m 20s
67- `pnpm lint`: ~35s
68- `pnpm format`: ~35s
69
70### Build Issues and Workarounds
71
72- **Docs build may fail** due to pnpm version mismatch in VitePress - this is expected in some environments
73- Use `pnpm build --filter="@hey-api/**"` to build packages without docs
74- **Some tests may fail** in sandboxed environments due to network restrictions (OpenAPI spec downloads)
75- **Generated test files** in `packages/openapi-ts-tests/` contain auto-generated snapshots that may have linting warnings - this is expected
76- **Linting issues** in `.gen/snapshots/` directories are expected for generated code
77
78## Validation
79
80### Manual Testing Scenarios
81
82After making changes, ALWAYS validate with these scenarios:
83
841. **CLI Functionality Test**:
85
86 ```bash
87 # Test CLI help
88 node packages/openapi-ts/dist/run.js --help
89
90 # Test CLI version
91 node packages/openapi-ts/dist/run.js --version
92
93 # Test basic code generation with a simple OpenAPI spec
94 # Create a minimal test spec and generate client code
95 node packages/openapi-ts/dist/run.js -i path/to/spec.json -o ./test-output --plugins "@hey-api/client-fetch" "@hey-api/typescript"
96 ```
97
982. **Example Application Test**:
99
100 ```bash
101 # Start fetch example and verify it loads
102 pnpm --filter @example/openapi-ts-fetch dev
103 # Should start on http://localhost:5173/
104 ```
105
1063. **Development Mode Test**:
107 ```bash
108 # Start dev mode and make a small change to verify rebuilding
109 pnpm --filter @hey-api/openapi-ts dev
110 ```
111
112### Pre-commit Validation
113
114ALWAYS run these commands before committing or the CI will fail:
115
116```bash
117# Use lint:fix to auto-fix issues (some warnings in generated test files are expected)
118pnpm lint:fix
119
120# Run typecheck (can target specific packages with --filter)
121pnpm typecheck
122
123# Run tests (some network tests may fail in sandboxed environments)
124pnpm test
125```
126
127**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.
128
129## Repository Structure
130
131### Key Packages
132
133- `packages/openapi-ts/` - Main CLI tool and library
134- `packages/codegen-core/` - Core code generation utilities
135- `packages/custom-client/` - Custom HTTP client implementations
136- `packages/nuxt/` - Nuxt.js integration
137- `packages/vite-plugin/` - Vite plugin
138
139### Examples
140
141- `examples/openapi-ts-fetch/` - Fetch client example (React + Vite)
142- `examples/openapi-ts-angular/` - Angular client example
143- `examples/openapi-ts-tanstack-react-query/` - TanStack React Query integration
144- `examples/openapi-ts-vue/` - Vue.js integration
145- Plus many more framework-specific examples
146
147### Configuration Files
148
149- `pnpm-workspace.yaml` - Workspace configuration
150- `turbo.json` - Turbo build configuration
151- `package.json` - Root package with workspace scripts
152- `.nvmrc` - Node.js version specification
153
154## Common Tasks
155
156### Working with the Main Package
157
158```bash
159# Install deps for main package
160pnpm --filter @hey-api/openapi-ts install
161
162# Build main package only
163pnpm --filter @hey-api/openapi-ts build
164
165# Test main package only
166pnpm --filter @hey-api/openapi-ts test
167
168# Start dev mode for main package
169pnpm --filter @hey-api/openapi-ts dev
170```
171
172### Working with Examples
173
174```bash
175# List all example packages
176ls examples/
177
178# Run specific example
179pnpm --filter @example/openapi-ts-fetch dev
180
181# Build all examples
182pnpm build --filter="@example/**"
183```
184
185### Debugging and Troubleshooting
186
187- Check `turbo.json` for task dependencies and configuration
188- Use `pnpm list` to see installed packages
189- Use `pnpm why <package>` to understand dependency chains
190- Check individual package `package.json` files for available scripts
191
192## CI/CD Pipeline
193
194The repository uses GitHub Actions (`.github/workflows/ci.yml`):
195
196- Tests on multiple Node.js versions
197- Tests on multiple OS (macOS, Ubuntu, Windows)
198- Runs build, lint, typecheck, and test commands
199- Publishes preview packages on PRs
200
201## Performance Expectations
202
203- **Cold install**: ~1m 20s
204- **Cold build**: ~2-5m depending on scope
205- **Incremental builds**: ~30s in dev mode
206- **Test suite**: ~1m 5s
207- **Linting**: ~35s
208- **Type checking**: ~1m 20s
209
210Remember: This is a complex monorepo with many dependencies. Be patient with build times and always use appropriate timeouts for long-running commands.