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-query skill For mocking generated API clients, see test-msw skill For schema validation, see zod skill Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md