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

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