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