orval

Files (48)

• AGENTS.md
• README.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• adv-form-data-handling.md · references/
• adv-input-transformer.md · references/
• adv-operation-override.md · references/
• adv-output-transformer.md · references/
• mock-delay-config.md · references/
• mock-http-status.md · references/
• mock-index-files.md · references/
• mock-msw-generation.md · references/
• mock-use-examples.md · references/
• mutator-body-wrapper.md · references/
• mutator-custom-instance.md · references/
• mutator-error-types.md · references/
• mutator-fetch-client.md · references/
• mutator-interceptors.md · references/
• mutator-token-refresh.md · references/
• oquery-hook-options.md · references/
• oquery-infinite-queries.md · references/
• oquery-key-export.md · references/
• oquery-mutation-callbacks.md · references/
• oquery-signal-cancellation.md · references/
• oquery-suspense-support.md · references/
• orvalcfg-baseurl-setup.md · references/
• orvalcfg-client-selection.md · references/
• orvalcfg-input-validation.md · references/
• orvalcfg-mode-selection.md · references/
• orvalcfg-prettier-format.md · references/
• orvalcfg-separate-schemas.md · references/
• output-clean-target.md · references/
• output-file-extension.md · references/
• output-headers-enabled.md · references/
• output-index-files.md · references/
• output-naming-convention.md · references/
• spec-operationid-unique.md · references/
• spec-required-fields.md · references/
• spec-response-types.md · references/
• spec-schemas-reusable.md · references/
• spec-tags-organization.md · references/
• types-bigint-support.md · references/
• types-use-dates.md · references/
• types-zod-coerce.md · references/
• types-zod-strict.md · references/
• types-zod-validation.md · references/

SKILL.md (first lines)

# 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](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules
- Example: [spec-operationid-unique](references/spec-operationid-unique.md)

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

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills