orval

Original：🇺🇸 English

Translated

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.

44installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-skills orval

SKILL.md Content

View Translation Comparison →

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-

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