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