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

spec-

orvalcfg-

output-

mutator-

oquery-

types-

mock-

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