How orval-labs/orval works
Project Type and Purpose
• This is a code-generation tool (a CLI/library) that parses OpenAPI v3 or Swagger v2 definitions and outputs API client code. Its purpose is to generate clients with proper TypeScript typings for different integration ecosystems.
• The README and samples indicate that the tool supports multiple frameworks (React Query, SWR, Angular, etc.), so it is effectively a generator engine with several adapters.
File Structure
• Top-level directories:
– “packages”: Contains sub-packages (core, angular, axios, fetch, hono, mock, orval, query, swr, zod). The “core” package likely encapsulates the common generator logic (reading specs, applying templates, outputting files) while the others are integration adapters.
– “docs”: Contains the documentation site, including components and pages that describe the tool.
– “samples”: Contains multiple example projects that show how to use the generated clients in different frameworks.
– “tests”: Contains a variety of test configurations, specifications, mutators, and regression tests.
– Additionally, many configuration files (.github, linting, prettier, etc.) indicate continuous integration, code formatting, and version management.
How to Represent the Architecture
a. Main Components (each should be clearly labeled):
• CLI/Configuration Interface: The entry point for reading user configuration (e.g., orval.config.ts) and invoking the generation process.
• Core Generation Engine (packages/core): This module parses OpenAPI/Swagger files, applies internal transformations, and orchestrates the generation process.
• Adapters/Integrations: Separate packages (angular, axios, fetch, hono, zod, etc.) that take the core output and generate framework-specific client code.
• File System Utilities & Writers: Located within “packages/core/src/utils” and “packages/core/src/writers” – responsible for file handling, merging, and output formatting.
• Documentation & Developer Resources: “docs” folder for the documentation website, and “samples” for usage examples.
• Testing/CI Infrastructure: “tests” with configuration files and GitHub workflows (in .github/workflows) ensuring quality through continuous testing and integration.
b. Relationships and Interactions:
• The CLI or configuration file feeds data into the Core Generation Engine.
• The Core module processes the OpenAPI/Swagger spec, generates an intermediate representation, and then hands off processing to specific adapters.
• Each adapter (e.g., for React Query, Angular, etc.) takes the processed model and generates client code tailored for its ecosystem.
• Utility modules support both the core engine and adapters by handling file I/O, templating, and logging.
• The documentation website (docs) and multiple samples demonstrate the usage of these generated clients.
c. Architectural Patterns and Design Principles:
• Modularity: The monorepo is divided into discrete packages (core, adapters, utilities) which communicate via well-defined contracts.
• Separation of Concerns: The core generation logic is separated from the framework-specific client adjustments.
• Extensibility: New adapters can be added without altering the core generation engine.
• Automation and Testing: Extensive test suites and CI/CD workflows ensure robustness.
d. Technologies and Frameworks:
• TypeScript for type safety during code generation.
• Node.js and NPM/Yarn for package management.
• GitHub Actions (workflows) for CI/CD.
• Various adapters are built for frameworks like React (React Query, SWR), Angular, Svelte, and Vue.