> orval
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.
curl "https://skillshub.wtf/pproenca/dot-skills/orval?format=md"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 operationIdsspec-schemas-reusable- Define reusable schemas in componentsspec-tags-organization- Organize operations with tagsspec-response-types- Define all response types explicitlyspec-required-fields- Mark required fields explicitly
2. Configuration Architecture (CRITICAL)
orvalcfg-mode-selection- Choose output mode based on API sizeorvalcfg-client-selection- Select client based on framework requirementsorvalcfg-separate-schemas- Separate schemas into dedicated directoryorvalcfg-input-validation- Validate OpenAPI spec before generationorvalcfg-baseurl-setup- Configure base URL properlyorvalcfg-prettier-format- Enable automatic code formatting
3. Output Structure & Organization (HIGH)
output-file-extension- Use distinct file extensions for generated codeoutput-index-files- Generate index files for clean importsoutput-naming-convention- Configure consistent naming conventionsoutput-clean-target- Enable clean mode for consistent regenerationoutput-headers-enabled- Enable headers in generated functions
4. Custom Client & Mutators (HIGH)
mutator-custom-instance- Use custom mutator for HTTP client configurationmutator-error-types- Export custom error types from mutatormutator-body-wrapper- Export body type wrapper for request transformationmutator-interceptors- Use interceptors for cross-cutting concernsmutator-token-refresh- Handle token refresh in mutatormutator-fetch-client- Use fetch mutator for smaller bundle size
5. Query Library Integration (MEDIUM-HIGH)
oquery-hook-options- Configure default query options globallyoquery-key-export- Export query keys for cache invalidationoquery-infinite-queries- Enable infinite queries for paginated endpointsoquery-suspense-support- Enable suspense mode for streaming UXoquery-signal-cancellation- Pass AbortSignal for request cancellationoquery-mutation-callbacks- Use generated mutation options types
6. Type Safety & Validation (MEDIUM)
types-zod-validation- Generate Zod schemas for runtime validationtypes-zod-strict- Enable Zod strict mode for safer validationtypes-zod-coerce- Use Zod coercion for type transformationstypes-use-dates- Enable useDates for Date type generationtypes-bigint-support- Enable useBigInt for large integer support
7. Mock Generation & Testing (MEDIUM)
mock-msw-generation- Generate MSW handlers for testingmock-use-examples- Use OpenAPI examples for realistic mocksmock-delay-config- Configure mock response delaysmock-http-status- Generate mocks for all HTTP status codesmock-index-files- Generate mock index files for easy setup
8. Advanced Patterns (LOW)
adv-input-transformer- Use input transformer for spec preprocessingadv-operation-override- Override settings per operationadv-output-transformer- Use output transformer for generated code modificationadv-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-queryskill - For mocking generated API clients, see
test-mswskill - For schema validation, see
zodskill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
> related_skills --same-repo
> rust-write-tests
Skill for writing expert-level Rust tests. Teaches the "What Could Break?" framework, five transformations from superficial to expert tests, flake hunting protocol, intent-based assertions, naming conventions, and a mandatory self-review checklist. Triggers on writing Rust tests, designing test cases, improving test quality, or reviewing test coverage.
> rust-implement
Write production-grade Rust code using a multi-pass approach. Design types first, then implement, then simplify, then verify with automated lint. Use this skill whenever writing new Rust functions, structs, modules, or features. Triggers on Rust implementation, new Rust code, Rust functions, Rust modules, error handling in Rust, async Rust, or type design in Rust.
> valid-skill
A valid test skill with proper formatting. This skill should pass all validations and serves as a reference for the expected format.
> too-long-skill
This skill has more than 500 lines which should fail validation.