agentsclimarketplace
Sign in

Orval

Skill ulpi-io/plugin-marketplace/plugins/pproenca/skills/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.From its SKILL.md

Install
npx -y skills add ulpi-io/plugin-marketplace --skill orval

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.2 KB, ~1.2k tokens by cl100k_base, as published. Nobody here has run it

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

PriorityCategoryImpactPrefix
1OpenAPI Specification QualityCRITICALspec-
2Configuration ArchitectureCRITICALorvalcfg-
3Output Structure & OrganizationHIGHoutput-
4Custom Client & MutatorsHIGHmutator-
5Query Library IntegrationMEDIUM-HIGHoquery-
6Type Safety & ValidationMEDIUMtypes-
7Mock Generation & TestingMEDIUMmock-
8Advanced PatternsLOWadv-

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

What ships with it: 47 files

95.6 KB alongside SKILL.md

assets/

references/

7 more files not listed here. See all 47 in the repository.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.