orval

Name: orval
Author: pproenca

github.com/pproencaDevelopment220334 installsUpdated 11w ago

About orval

orval is a best-practices skill for developers generating type-safe TypeScript clients from OpenAPI specifications. Its prioritized rules cover configuration, query-library hooks, validation, mocks, and testing.

Key features

0142 rules across 8 categories
02Prioritized OpenAPI and configuration guidance
03React Query, SWR, and Vue Query integration
04Custom mutators and type validation
05MSW mock generation and testing

Use cases

01Configuring Orval for a new project
02Generating TypeScript clients from OpenAPI
03Integrating generated hooks with query libraries
04Setting up API mocks and tests

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/pproenca/dot-skills --skill orval

After installing, type/orvalin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

AGENTS.md

metadata.json

README.md

assets/templates/

_template.md

references/

_sections.md

adv-form-data-handling.md

adv-input-transformer.md

adv-operation-override.md

adv-output-transformer.md

mock-delay-config.md

mock-http-status.md

mock-index-files.md

mock-msw-generation.md

mock-use-examples.md

mutator-body-wrapper.md

mutator-custom-instance.md

mutator-error-types.md

mutator-fetch-client.md

mutator-interceptors.md

mutator-token-refresh.md

oquery-hook-options.md

oquery-infinite-queries.md

oquery-key-export.md

oquery-mutation-callbacks.md

oquery-signal-cancellation.md

oquery-suspense-support.md

orvalcfg-baseurl-setup.md

orvalcfg-client-selection.md

orvalcfg-input-validation.md

orvalcfg-mode-selection.md

Details

From the project README

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

Comments

Markdown supported

Details

Author: pproenca
Repository: pproenca/dot-skills
Category: Development
Installs: 334
GitHub stars: 220

Report

More skills

All skills

remotion-render

github.com/inference-sh

1.6M

Render videos from React/Remotion component code via inference.sh. Pass TSX code, get MP4. Supports all Remotion APIs: useCurrentFrame, useVideoConfig, spring, interpolate, AbsoluteFill, Sequence. Configurable resolution, FPS, duration, codec. Use for: programmatic video generation, animated graphics, motion design, data-driven videos, React animations to video. Triggers: remotion, render video from code, tsx to video, react video, programmatic video, remotion render, code to video, animated video, motion graphics code, react animation video

improve-codebase-architecture

github.com/mattpocock

1.2M

Scan a codebase for architecture improvement opportunities, present them as a visual HTML report, then dive deep into whichever one you pick.

design-mobile-apps

github.com/designed-by-ai

1.1M

Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML

vercel-react-best-practices

github.com/vercel-labs

855.5k

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.