Orval

If you're generating TypeScript clients from OpenAPI specs, this covers the full workflow from config to testing. It's organized into 42 rules across 8 categories, from spec quality and orval.config.ts setup through React Query/SWR integration, custom mutators for auth, and MSW mock generation. The priority system is helpful because it steers you toward critical decisions first, like choosing the right output mode and client type, before you get into the weeds of Zod validation or infinite queries. It assumes you already know why you want Orval but need the patterns for doing it right. The mutator and query key sections are where most teams will spend their time once the basics work.

skills.sh installs: 338
GitHub stars: 222
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add pproenca/dot-skills --skill orval --agent claude-code

Installs into .claude/skills of the current project.

Files

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-`