Orval OpenAPI Best Practices
Comprehensive guide for generating type-safe TypeScript clients from OpenAPI specifications using Orval. Contains 42 rules across 8 categories, prioritized by impact to guide automated configuration, client generation, and testing setup.
When to Apply
Reference these guidelines when:
- •Configuring Orval for a new project
- •Setting up OpenAPI-based TypeScript client generation
- •Integrating React Query, SWR, or Vue Query with generated hooks
- •Creating custom mutators for authentication and error handling
- •Generating MSW mocks for testing
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | OpenAPI Specification Quality | CRITICAL | spec- |
| 2 | Configuration Architecture | CRITICAL | orvalcfg- |
| 3 | Output Structure & Organization | HIGH | output- |
| 4 | Custom Client & Mutators | HIGH | mutator- |
| 5 | Query Library Integration | MEDIUM-HIGH | oquery- |
| 6 | Type Safety & Validation | MEDIUM | types- |
| 7 | Mock Generation & Testing | MEDIUM | mock- |
| 8 | Advanced Patterns | LOW | adv- |
Quick Reference
1. OpenAPI Specification Quality (CRITICAL)
- •
spec-operationid-unique- Use unique and descriptive operationIds - •
spec-schemas-reusable- Define reusable schemas in components - •
spec-tags-organization- Organize operations with tags - •
spec-response-types- Define all response types explicitly - •
spec-required-fields- Mark required fields explicitly
2. Configuration Architecture (CRITICAL)
- •
orvalcfg-mode-selection- Choose output mode based on API size - •
orvalcfg-client-selection- Select client based on framework requirements - •
orvalcfg-separate-schemas- Separate schemas into dedicated directory - •
orvalcfg-input-validation- Validate OpenAPI spec before generation - •
orvalcfg-baseurl-setup- Configure base URL properly - •
orvalcfg-prettier-format- Enable automatic code formatting
3. Output Structure & Organization (HIGH)
- •
output-file-extension- Use distinct file extensions for generated code - •
output-index-files- Generate index files for clean imports - •
output-naming-convention- Configure consistent naming conventions - •
output-clean-target- Enable clean mode for consistent regeneration - •
output-headers-enabled- Enable headers in generated functions
4. Custom Client & Mutators (HIGH)
- •
mutator-custom-instance- Use custom mutator for HTTP client configuration - •
mutator-error-types- Export custom error types from mutator - •
mutator-body-wrapper- Export body type wrapper for request transformation - •
mutator-interceptors- Use interceptors for cross-cutting concerns - •
mutator-token-refresh- Handle token refresh in mutator - •
mutator-fetch-client- Use fetch mutator for smaller bundle size
5. Query Library Integration (MEDIUM-HIGH)
- •
oquery-hook-options- Configure default query options globally - •
oquery-key-export- Export query keys for cache invalidation - •
oquery-infinite-queries- Enable infinite queries for paginated endpoints - •
oquery-suspense-support- Enable suspense mode for streaming UX - •
oquery-signal-cancellation- Pass AbortSignal for request cancellation - •
oquery-mutation-callbacks- Use generated mutation options types
6. Type Safety & Validation (MEDIUM)
- •
types-zod-validation- Generate Zod schemas for runtime validation - •
types-zod-strict- Enable Zod strict mode for safer validation - •
types-zod-coerce- Use Zod coercion for type transformations - •
types-use-dates- Enable useDates for Date type generation - •
types-bigint-support- Enable useBigInt for large integer support
7. Mock Generation & Testing (MEDIUM)
- •
mock-msw-generation- Generate MSW handlers for testing - •
mock-use-examples- Use OpenAPI examples for realistic mocks - •
mock-delay-config- Configure mock response delays - •
mock-http-status- Generate mocks for all HTTP status codes - •
mock-index-files- Generate mock index files for easy setup
8. Advanced Patterns (LOW)
- •
adv-input-transformer- Use input transformer for spec preprocessing - •
adv-operation-override- Override settings per operation - •
adv-output-transformer- Use output transformer for generated code modification - •
adv-form-data-handling- Configure form data serialization
How to Use
Read individual reference files for detailed explanations and code examples:
- •Section definitions - Category structure and impact levels
- •Rule template - Template for adding new rules
- •Example: spec-operationid-unique
Related Skills
- •For consuming generated hooks, see
tanstack-queryskill - •For mocking generated API clients, see
test-mswskill - •For schema validation, see
zodskill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md