Agent-Skills.md

Agent Skills: Orval OpenAPI Best Practices

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.

UncategorizedID: pproenca/dot-skills/orval

Repository

pproenca/dot-skills
pproenca

Install this agent skill to your local

pnpm dlx add-skill https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/orval

Skill Files

Browse the full folder contents for orval.

Download Skill

Loading file tree…

skills/.experimental/orval/SKILL.md

Skill Metadata

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:

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