Architecture

Understanding the design and architecture of nuxt-openapi-hyperfetch.

Overview

Nuxt OpenAPI Hyperfetch is a CLI tool that generates type-safe Nuxt composables from OpenAPI specifications. It bridges the gap between your API documentation and your frontend code.

Core Concepts

Code Generation

Generate composables at build time, not runtime:

Static Generation - All composables generated as TypeScript files
Type Safety - Full type inference from OpenAPI schemas
Tree Shakeable - Only import what you use
No Runtime Overhead - Pure TypeScript, no parser at runtime

Dual Mode

Support both client and server environments:

Client Mode - Generate useFetch/useAsyncData composables for Vue components
Server Mode - Generate server composables for Nitro routes (BFF pattern)

OpenAPI First

Let your API specification be the source of truth:

Schema to Types - OpenAPI schemas → TypeScript interfaces
Operations to Composables - API operations → Type-safe functions
Documentation to Comments - OpenAPI descriptions → JSDoc comments

Architecture Sections

Design Patterns

Common patterns used in generated code:

Architecture Decisions

Key decisions and their rationale:

System Architecture

┌─────────────────────────────────────────────────┐
│              OpenAPI Specification              │
│         (swagger.yaml / openapi.json)           │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│           nuxt-openapi-hyperfetch CLI                    │
│  ┌──────────────────────────────────────────┐   │
│  │  Parser (OpenAPI → AST)                  │   │
│  └──────────────┬───────────────────────────┘   │
│                 ▼                               │
│  ┌──────────────────────────────────────────┐   │
│  │  Type Generator (Schemas → Interfaces)   │   │
│  └──────────────┬───────────────────────────┘   │
│                 ▼                               │
│  ┌──────────────────────────────────────────┐   │
│  │  Composable Generator (Operations)       │   │
│  └──────────────┬───────────────────────────┘   │
│                 ▼                               │
│  ┌──────────────────────────────────────────┐   │
│  │  File Writer (TS files)                  │   │
│  └──────────────────────────────────────────┘   │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│          Generated Composables                  │
│                                                  │
│  composables/                                    │
│  ├── pets/                                       │
│  │   ├── useFetchPet.ts                         │
│  │   └── useCreatePet.ts                        │
│  └── types.ts                                    │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│              Your Nuxt App                      │
│                                                  │
│  <script setup>                                  │
│  const { data } = useFetchPet(1)                │
│  </script>                                       │
└─────────────────────────────────────────────────┘

Contributing

Want to contribute? See the Contributing Guide →.

Architecture ​

Overview ​

Core Concepts ​

Code Generation ​

Dual Mode ​

OpenAPI First ​

Architecture Sections ​

Design Patterns ​

Architecture Decisions ​

System Architecture ​

Contributing ​

Next Steps ​