---

name: orval description: Orval OpenAPI TypeScript client generation best practices. This skill should be used when configuring Orval, generating TypeScript clients from OpenAPI specs, setting up React Query/SWR hooks, creating custom mutators, or writing MSW mocks. Triggers on tasks involving orval.config.ts, OpenAPI codegen, API client setup, or mock generation.

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