Orval

https://orval.dev
Admin
Orval is a code generator that creates clients, types, and mocks for frontend applications based on...
Tokens:62,555
Snippets:760
Trust Score:8.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Verify installation (Yarn)

Source: https://orval.dev/docs/installation

Verify Orval installation using yarn.

```bash
yarn orval --version
```

--------------------------------

### Verify installation (Bun)

Source: https://orval.dev/docs/installation

Verify Orval installation using bunx.

```bash
bunx orval --version
```

--------------------------------

### Global installation (Yarn)

Source: https://orval.dev/docs/installation

Install Orval globally using Yarn.

```bash
yarn global add orval
```

--------------------------------

### Global installation (Bun)

Source: https://orval.dev/docs/installation

Install Orval globally using Bun.

```bash
bun add -g orval
```

--------------------------------

### Global installation (pnpm)

Source: https://orval.dev/docs/installation

Install Orval globally using pnpm.

```bash
pnpm add -g orval
```

--------------------------------

### Verify installation (pnpm)

Source: https://orval.dev/docs/installation

Verify Orval installation using pnpm.

```bash
pnpm orval --version
```

--------------------------------

### Verify installation (npm)

Source: https://orval.dev/docs/installation

Verify Orval installation using npx.

```bash
npx orval --version
```

--------------------------------

### Global installation (npm)

Source: https://orval.dev/docs/installation

Install Orval globally using npm.

```bash
npm install orval -g
```

--------------------------------

### Configure Solid Query Client

Source: https://orval.dev/docs/versions/v8

Example configuration to enable Solid Query or SolidStart support.

```typescript
export default defineConfig({
  petstore: {
    output: {
      client: 'solid-query',
      target: './src/api',
    },
  },
});
```

--------------------------------

### Configure Angular Query Client

Source: https://orval.dev/docs/versions/v8

Example configuration to enable Angular Query support.

```typescript
export default defineConfig({
  petstore: {
    output: {
      client: 'angular-query',
      target: './src/api',
    },
  },
});
```

--------------------------------

### Install Orval with pnpm

Source: https://orval.dev/docs/installation

Install Orval as a dev dependency using pnpm.

```bash
pnpm add orval -D
```

--------------------------------

### Basic MSW setup with setupServer

Source: https://orval.dev/docs/guides/msw

Use aggregated handler functions with MSW's setupServer for Node.js environments.

```typescript
import { getPetsMock } from './api/petstore.msw';
import { setupServer } from 'msw/node';

const server = setupServer(...getPetsMock());

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

--------------------------------

### Install Orval with npm

Source: https://orval.dev/docs/installation

Install Orval as a dev dependency using npm.

```bash
npm install orval -D
```

--------------------------------

### Install Orval with Yarn

Source: https://orval.dev/docs/installation

Install Orval as a dev dependency using Yarn.

```bash
yarn add orval -D
```

--------------------------------

### Configure Axios HTTP Client

Source: https://orval.dev/docs/versions/v8

Example configuration to continue using axios as the HTTP client instead of the default fetch.

```typescript
export default defineConfig({
  petstore: {
    output: {
      httpClient: 'axios',
      target: './src/api',
    },
  },
});
```

--------------------------------

### Configure Runtime Validation

Source: https://orval.dev/docs/versions/v8

Example configuration to enable runtime validation using the fetch client.

```typescript
export default defineConfig({
  petstore: {
    output: {
      schemas: { type: 'zod' },
      client: 'fetch',
      override: {
        fetch: {
          runtimeValidation: { strategy: 'both' },
        },
      },
    },
  },
});
```

--------------------------------

### Example directory structure for routed schemas

Source: https://orval.dev/docs/reference/configuration/output

Visual representation of the file structure generated when using routes for default models and enums.

```text
schemas/
├── models/
│   ├── index.ts
│   └── pet.ts
├── types/
│   ├── index.ts
│   └── petStatus.ts
└── index.ts
```

--------------------------------

### Install Orval via Bun

Source: https://orval.dev/

Use the Bun package manager to add Orval as a development dependency.

```bash
$bun add -d orval
```

--------------------------------

### OpenAPI Specification Example

Source: https://orval.dev/

A sample OpenAPI 3.0.0 specification file named petstore.yaml defining a Pet schema and a listPets operation.

```yaml
openapi: 3.0.0info:  title: Pet Store API  version: 1.0.0paths:  /pets:    get:      operationId: listPets      responses:        200:          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/Pet'components:  schemas:    Pet:      type: object      properties:        id:          type: integer        name:          type: string
```

--------------------------------

### Build Scripts Integration

Source: https://orval.dev/docs/reference/integration

Example of integrating Orval into package.json scripts and a custom generation script.

```json
{
  "scripts": {
    "generate": "node scripts/generate-api.js",
    "dev": "npm run generate && next dev",
    "build": "npm run generate && next build"
  }
}
```

```javascript
const { generate } = require('orval');

async function main() {
  try {
    await generate();
    console.log('API client generated successfully');
  } catch (error) {
    console.error('Failed to generate API client:', error);
    process.exit(1);
  }
}

main();
```

--------------------------------

### Usage Example

Source: https://orval.dev/docs/guides/stream-ndjson

Consume the stream using the generated function and the readStream helper.

```typescript
export const getResults = async (): Promise<StreamEntry[]> => {
  const results: StreamEntry[] = [];

  const response = await stream();
  if (response.status !== 200) return results;

  await readStream(response.stream, (obj) => {
    // obj is typed as StreamEntry
    results.push(obj);
  });

  return results;
};
```

--------------------------------

### Generated Svelte Query Store Example

Source: https://orval.dev/docs/guides/svelte-query

Orval generates a custom store for each path in your OpenAPI specification. This example shows the structure of a generated store for `showPetById`, including query key generation and a hook for use with `useQuery`.

```typescript
export const showPetById = (
  petId: string,
  options?: AxiosRequestConfig,
): Promise<AxiosResponse<Pet>> => {
  return axios.get(`/pets/${petId}`, options);
};

export const getShowPetByIdQueryKey = (petId: string) => [`/pets/${petId}`];

export const useShowPetById = <
  TData = AsyncReturnType<typeof showPetById>,
  TError = Error,
>(
  petId: string,
  options?: {
    query?: UseQueryOptions<AsyncReturnType<typeof showPetById>, TError, TData>;
    axios?: AxiosRequestConfig;
  },
) => {
  const { query: queryOptions, axios: axiosOptions } = options ?? {};

  const queryKey = queryOptions?.queryKey ?? getShowPetByIdQueryKey(petId);
  const queryFn = () => showPetById(petId, axiosOptions);

  const query = useQuery<AsyncReturnType<typeof queryFn>, TError, TData>(
    queryKey,
    queryFn,
    {
      enabled: petId !== null && petId !== undefined,
      ...queryOptions,
    },
  );

  return {
    queryKey,
    ...query,
  };
};
```

--------------------------------

### Configure Zod Schema Generation

Source: https://orval.dev/docs/versions/v8

Example configuration to set the schema output type to Zod.

```typescript
export default defineConfig({
  petstore: {
    output: {
      schemas: {
        path: './model',
        type: 'zod', // 'typescript' | 'zod'
      },
    },
  },
});
```

--------------------------------

### Testing with Vitest

Source: https://orval.dev/docs/guides/msw

Example of using Vitest mocks to verify that the handler receives the expected parameters.

```typescript
import { expect, vi } from 'vitest';
import { getShowPetByIdMockHandler, getShowPetByIdResponseMock } from './api/petstore.msw';

const mockFn = vi.fn();

const handlers = [
  getShowPetByIdMockHandler(async (info) => {
    mockFn(info.params.petId);
    return getShowPetByIdResponseMock();
  }),
];

// ... run test

expect(mockFn).toHaveBeenCalledWith('123');
```

--------------------------------

### Regular Zod Bundle Output

Source: https://orval.dev/docs/guides/zod

Example of how regular Zod output might appear in a bundle when unused.

```typescript
// possible bundled regular Zod output (no export const User, but the zod call is still there)
object({
  email: email().min(userEmailMin).max(userEmailMax),
});
```

--------------------------------

### Configure Angular client options

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for Angular client settings including DI scope and retrieval client type in orval.config.ts.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        angular: {
          provideIn: 'root', // 'root' | 'any' | '' | false
          retrievalClient: 'httpClient',
          runtimeValidation: true,
          httpResource: {
            debugName: 'getPetByIdResource',
          },
        },
      },
    },
  },
});
```

--------------------------------

### Implementing a custom server with Hono

Source: https://orval.dev/docs/guides/mcp

Example of a custom server implementation using Hono and StreamableHTTPTransport. Ensure this file is placed outside the generated output directory.

```typescript
import type {
  McpServer,
  RegisteredTool,
} from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPTransport } from '@hono/mcp';
import { Hono } from 'hono';

export const customServer = (
  createMcpServer: (options?: RequestInit) => {
    server: McpServer;
    tools: Record<string, RegisteredTool>;
  },
) => {
  const app = new Hono();
  const { server } = createMcpServer();
  const transport = new StreamableHTTPTransport();

  app.all('/mcp', async (c) => {
    if (!server.isConnected()) {
      await server.connect(transport);
    }
    return transport.handleRequest(c);
  });

  Bun.serve({ fetch: app.fetch, port: Number(process.env.PORT ?? 3000) });
};
```

--------------------------------

### Zod Mini Bundle Output

Source: https://orval.dev/docs/guides/zod

Example of how Zod Mini output might appear in a bundle when unused.

```typescript
// possible bundled Zod Mini output
// no User schema code emitted at all
```

--------------------------------

### Configuring useHooks for Options Factories

Source: https://orval.dev/docs/reference/configuration/output

Example orval.config.ts showing how to set useHooks to false to generate get-prefixed factories.

```typescript
export default defineConfig({
  petstore: {
    output: {
      client: 'react-query',
      override: {
        query: {
          queryOptions: {
            path: './src/mutators/custom-query-options.ts',
            name: 'customQueryOptions',
            useHooks: false,
          },
          mutationOptions: {
            path: './src/mutators/custom-mutation-options.ts',
            name: 'customMutationOptions',
            useHooks: false,
          },
        },
      },
    },
  },
});
```

--------------------------------

### Configure TanStack Query options in orval.config.ts

Source: https://orval.dev/docs/reference/configuration/output

Example showing the full range of TanStack Query override options available within the output configuration.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        query: {
          useQuery: true,
          useSuspenseQuery: true,
          useMutation: true,
          useInfinite: true,
          useSuspenseInfiniteQuery: true,
          useInfiniteQueryParam: 'nextId',
          usePrefetch: true,
          useInvalidate: true,
          useSetQueryData: true,
          useGetQueryData: true,
          signal: true,
          runtimeValidation: true,
          options: {
            staleTime: 10000,
          },
        },
      },
    },
  },
});
```

--------------------------------

### Implement custom parameter serializers

Source: https://orval.dev/docs/reference/configuration/output

Example implementations for custom parameter serializers. The first is for Axios/Angular, and the second is for the fetch client, which must return a string.

```typescript
// Axios / Angular
export const customParamsSerializerFn = (
  params: Record<string, any>,
): string => {
  return Object.entries(params)
    .filter(([_, v]) => v !== undefined)
    .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
    .join('&');
};

// fetch client — must return a string
export const customParamsSerializer = (
  params: Record<string, unknown> | undefined,
): string =>
  new URLSearchParams(
    Object.entries(params ?? {})
      .filter(([_, v]) => v !== undefined)
      .flatMap(([k, v]) =>
        Array.isArray(v)
          ? v.map((item) => [k, String(item)])
          : [[k, String(v)]],
      ),
  ).toString();
```

--------------------------------

### Configure clean to preserve swagger.json

Source: https://orval.dev/docs/reference/configuration/output

Example of using the clean option to keep a specific file, such as swagger.json, within the target directory.

```typescript
export default defineConfig({
  petstore: {
    output: {
      target: './src/generated',
      clean: ['!**/swagger.json'],
    },
  },
});
```

--------------------------------

### Generated Response Factory Example

Source: https://orval.dev/docs/guides/faker

By default, Orval emits a get<OperationId>ResponseMock factory that returns a fully-populated response value.

```typescript
import { faker } from '@faker-js/faker';

export const getShowPetByIdResponseMock = (
  overrideResponse: Partial<Pet> = {},
): Pet => ({
  id: faker.number.int({ min: undefined, max: undefined }),
  name: faker.string.alpha(20),
  tag: faker.string.alpha(20),
  ...overrideResponse,
});
```

--------------------------------

### Configure SWR output overrides

Source: https://orval.dev/docs/reference/configuration/output

Example of configuring SWR hook generation options such as useInfinite, useSuspense, and custom SWR hook options within orval.config.ts.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        swr: {
          useInfinite: true,
          useSuspense: true,
          generateErrorTypes: false,
          swrOptions: {
            dedupingInterval: 10000,
          },
          swrMutationOptions: {
            revalidate: true,
          },
          swrInfiniteOptions: {
            initialSize: 10,
          },
        },
      },
    },
  },
});
```

--------------------------------

### Configure Hono output options in orval.config.ts

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for Hono output overrides, including handler paths, generation strategies, and validator/route output paths.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        hono: {
          handlers: 'src/handlers',
          handlerGenerationStrategy: 'smart',
          validatorOutputPath: 'src/validator.ts',
          compositeRoute: 'src/routes.ts',
        },
      },
    },
  },
});
```

--------------------------------

### File structure with schemas configured

Source: https://orval.dev/docs/reference/configuration/output

Shows the directory structure when schemas are configured, demonstrating how models are organized in a shared directory.

```text
my-app/src/
├── models/
│   ├── index.ts
│   ├── pet.ts
│   ├── listResponse.ts
│   ├── pagination.ts
│   └── userListResponse.ts
├── pets/
│   └── pets.ts              ← imports from ../models
└── users/
    └── users.ts             ← imports from ../models
```

--------------------------------

### preserveReadonlyRequestBodies configuration

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for setting preserveReadonlyRequestBodies to 'strip' in orval.config.ts.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        preserveReadonlyRequestBodies: 'strip',
      },
    },
  },
});
```

--------------------------------

### Build Docker Image

Source: https://orval.dev/docs/guides/mcp

Build the Docker image for your MCP server using the provided Dockerfile.

```bash
docker build ./ -t mcp-petstore
```

--------------------------------

### Cross-tag import resolution

Source: https://orval.dev/docs/reference/configuration/output

Example of how imports are resolved when schemas are organized into tag subdirectories.

```typescript
// pets/pet.ts
import type { Error } from '../shared/error';
```

--------------------------------

### Run Orval with Docker and environment variables (Linux native)

Source: https://orval.dev/docs/installation

Run Orval with environment variables and host mapping for native Linux Docker.

```bash
docker run --rm --add-host=host.docker.internal:host-gateway \
  -v "$(pwd):/app" \
  -w /app \
  -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
  ghcr.io/orval-labs/orval \
  --config ./orval.config.ts
```

--------------------------------

### Configure factoryMethods in orval.config.ts

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for the factoryMethods object within an Orval project definition.

```typescript
export default defineConfig({
  petstore: {
    output: {
      factoryMethods: {
        functionNamePrefix: 'create',
        mode: 'split',
        includeOptionalProperty: true,
        outputDirectory: `#output.workspace.schemas`,
      },
    },
  },
});
```

--------------------------------

### Run Orval with Docker (Windows CMD)

Source: https://orval.dev/docs/installation

Basic Docker usage for Windows CMD.

```bash
docker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orval
```

--------------------------------

### Configure tagsSplitDeduplication in orval.config.ts

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for enabling tags-split mode with deduplication enabled in orval.config.ts.

```typescript
export default defineConfig({
  petstore: {
    output: {
      mode: 'tags-split',
      target: './src/api/endpoints.ts',
      schemas: './src/api/model',
      client: 'fetch',
      indexFiles: true,
      tagsSplitDeduplication: true,
    },
  },
});
```

--------------------------------

### Faker mock configuration in orval.config.ts

Source: https://orval.dev/docs/guides/faker

Example configuration for the Faker generator within the orval.config.ts file.

```typescript
mock: {
  generators: [
    {
      type: 'faker',
      useExamples: true,
      generateEachHttpStatus: true,
      locale: 'en_GB',
      preferredContentType: 'application/json',
      arrayItems: true,
    },
  ],
}
```

--------------------------------

### Run Orval with a configuration file

Source: https://orval.dev/docs/quick-start

Use the --config flag to point to a specific configuration file, or run 'orval' to automatically detect files like orval.config.js.

```bash
orval --config ./orval.config.js
# or simply
orval
```

--------------------------------

### Configure unsafeDisableValidation in orval.config.ts

Source: https://orval.dev/docs/reference/configuration/input

Example of enabling unsafeDisableValidation within the input configuration of an Orval project.

```typescript
import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
      unsafeDisableValidation: true,
    },
  },
});
```

--------------------------------

### Run Orval with Docker (macOS / Linux)

Source: https://orval.dev/docs/installation

Basic Docker usage for macOS or Linux.

```bash
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
```

--------------------------------

### Run Orval with config file (macOS / Linux)

Source: https://orval.dev/docs/installation

Run Orval with a configuration file on macOS or Linux.

```bash
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
```

--------------------------------

### Specify Configuration File

Source: https://orval.dev/docs/reference/cli

Points to a specific Orval configuration file.

```bash
orval --config ./api/orval.config.js
```

--------------------------------

### Configure Orval for SolidStart

Source: https://orval.dev/docs/guides/solid-start

Set the 'client' option to 'solid-start' in your 'orval.config.ts' file to enable SolidStart primitive generation.

```typescript
import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    output: {
      mode: 'tags-split',
      target: 'src/api/petstore.ts',
      schemas: 'src/api/model',
      client: 'solid-start',
      mock: true,
    },
    input: {
      target: './petstore.yaml',
    },
  },
});
```

--------------------------------

### Run Orval with config file (Windows CMD)

Source: https://orval.dev/docs/installation

Run Orval with a configuration file on Windows CMD.

```bash
docker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
```

--------------------------------

### Self-referential $dynamicAnchor OpenAPI 3.1 Spec

Source: https://orval.dev/docs/reference/configuration/output

Example of recursive schemas where $dynamicRef resolves to the declaring schema itself.

```yaml
components:
  schemas:
    BaseCategory:
      $dynamicAnchor: category
      type: object
      properties:
        id:
          type: string
        children:
          type: array
          items:
            $dynamicRef: '#category'

    LocalizedCategory:
      $dynamicAnchor: category
      allOf:
        - $ref: '#/components/schemas/BaseCategory'
        - type: object
          properties:
            displayName:
              type: string
```

--------------------------------

### Focus on Specific Projects

Source: https://orval.dev/docs/reference/cli

Targets specific projects defined within the configuration file.

```bash
orval --project petstore
orval --project dogstore catstore
```

--------------------------------

### Configure Effect schema generation

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for Effect schema generation options within orval.config.ts.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        effect: {
          strict: {
            response: true,
            query: true,
            param: true,
            header: true,
            body: true,
          },
          generate: {
            param: true,
            body: true,
            response: true,
            query: true,
            header: true,
          },
          generateEachHttpStatus: true,
          useBrandedTypes: true,
        },
      },
    },
  },
});
```

--------------------------------

### Generate API client via CLI

Source: https://orval.dev/docs/quick-start

The simplest way to use Orval is directly from the command line by specifying the input OpenAPI specification and the output path.

```bash
orval --input ./petstore.yaml --output ./src/petstore.ts
```

--------------------------------

### Generated Zod Schema Example

Source: https://orval.dev/docs/guides/zod

Orval produces a Zod schema for each model defined in the OpenAPI specification.

```typescript
export const CreatePetsBody = /*#__PURE__*/ zod.object({
  id: /*#__PURE__*/ zod.number(),
  name: /*#__PURE__*/ zod.string(),
  tag: /*#__PURE__*/ zod.optional(/*#__PURE__*/ zod.string()),
});
```

--------------------------------

### Check Node.js Version

Source: https://orval.dev/docs/versions/v8

Verify that the environment meets the minimum Node.js requirement of 22.18.0.

```bash
# Check your Node.js version
node --version  # Should be >= 22.18.0
```

--------------------------------

### Generated useDatesTransform Response Function

Source: https://orval.dev/docs/reference/configuration/output

Example of the generated deserialize function chained to an operation call when useDatesTransform is enabled.

```typescript
export const getOrderDetails = (orderId: string) => {
  return customInstance<OrderDetails>({ url: `/orders/${orderId}`, method: 'GET' }).then(
    deserializeGetOrderDetailsResponse,
  );
};
```

--------------------------------

### Run Orval with Docker (Windows PowerShell)

Source: https://orval.dev/docs/installation

Basic Docker usage for Windows PowerShell.

```bash
docker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orval
```

--------------------------------

### Read OpenAPI URL from environment variable

Source: https://orval.dev/docs/installation

Example of reading the OpenAPI URL from an environment variable in your config file.

```typescript
const inputTarget =
  process.env.ORVAL_SWAGGER_URL ?? 'https://localhost:7142/swagger/v1/swagger.json';
```

--------------------------------

### Run Orval with config file (Windows Git Bash)

Source: https://orval.dev/docs/installation

Run Orval with a configuration file on Windows Git Bash.

```bash
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
```

--------------------------------

### Generated code using customInstance

Source: https://orval.dev/docs/guides/solid-start

Example of how Orval generates code that utilizes the specified customInstance for API requests.

```typescript
export const SwaggerPetstore = {
  showPetById: query(async (petId: string) => {
    const url = `/pets/${petId}`;
    return customInstance<Pet>(url, {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' },
    });
  }, 'showPetById'),
};
```

--------------------------------

### Basic Usage of Orval API

Source: https://orval.dev/docs/reference/integration

Demonstrates how to trigger code generation using a configuration file path or the current directory's configuration.

```typescript
import orval from 'orval';

// Generate using a config file path
await orval('./orval.config.js');

// Generate using current directory's orval config
await orval();
```

--------------------------------

### Run Orval with Docker (Windows Git Bash)

Source: https://orval.dev/docs/installation

Basic Docker usage for Windows Git Bash, using MSYS_NO_PATHCONV to handle paths correctly.

```bash
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
```

--------------------------------

### Generated Fetch Client Output

Source: https://orval.dev/docs/guides/fetch-client

Example of the generated fetch-based functions and hooks produced by Orval for SWR or TanStack Query.

```typescript
export type listPetsResponse = {
  data: Pets | BadRequest;
  status: number;
};

export const getListPetsUrl = (params?: ListPetsParams) => {
  const normalizedParams = new URLSearchParams();

  Object.entries(params || {}).forEach(([key, value]) => {
    if (value === null) {
      normalizedParams.append(key, 'null');
    } else if (value !== undefined) {
      normalizedParams.append(key, value.toString());
    }
  });

  return normalizedParams.size
    ? `http://localhost:8000/pets?${normalizedParams.toString()}`
    : `http://localhost:8000/pets`;
};

export const listPets = async (
  params?: ListPetsParams,
  options?: RequestInit,
): Promise<listPetsResponse> => {
  const res = await fetch(getListPetsUrl(params), {
    ...options,
    method: 'GET',
  });
  const data: Pets =
    [204, 205, 304].includes(res.status) || !res.body ? {} : await res.json();

  return { status: res.status, data };
};

export const useListPets = <TError = Promise<Pets | Error>>(
  params?: ListPetsParams,
  options?: {
    swr?: SWRConfiguration<Awaited<ReturnType<typeof listPets>>, TError>;
    fetch?: RequestInit;
  },
) => {
  // ... hook implementation
};
```

--------------------------------

### Run the Hono Server

Source: https://orval.dev/docs/guides/hono

Use wrangler to run the generated Hono application and test the endpoint.

```bash
wrangler dev src/petstore.ts
curl http://localhost:8787/pets
# => [{"id":1,"name":"Buddy"},{"id":2,"name":"Max"}]
```

--------------------------------

### Configuring Schema Factories

Source: https://orval.dev/docs/guides/faker

Set schemas: true in your orval.config.ts to emit a get<SchemaName>Mock() factory for each entry under components/schemas.

```typescript
mock: {
  generators: [
    {
      type: 'faker',
      schemas: true,            // emit components/schemas factories
      operationResponses: true, // also emit per-operation response factories (default)
    },
  ],
}
```

--------------------------------

### Run Orval with Docker and environment variables (Windows CMD)

Source: https://orval.dev/docs/installation

Run Orval with environment variables on Windows CMD.

```bash
cd /d "C:\path\to\your-project"
docker run --rm -v "%cd%:/app" -w /app -e ORVAL_SWAGGER_URL=https://host.docker.internal:7142/swagger/v1/swagger.json -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
```

--------------------------------

### Get Query Data helper function

Source: https://orval.dev/docs/guides/vue-query

Generated helper function to read cached query data using getQueryData.

```typescript
export const getListPetsQueryData = (
  queryClient: QueryClient,
  params: ListPetsParams,
) =>
  queryClient.getQueryData<Awaited<ReturnType<typeof listPets>>>(
    getListPetsQueryKey(params),
  );
```

--------------------------------

### File structure for tags-split mode

Source: https://orval.dev/docs/reference/configuration/output

Shows the file structure when mode is set to tags-split.

```text
my-app/src/
├── petstore.schemas.ts
└── pets/
    ├── petstore.msw.ts
    └── petstore.ts
```

--------------------------------

### File structure for split mode

Source: https://orval.dev/docs/reference/configuration/output

Shows the file structure when mode is set to split.

```text
my-app/src/
├── petstore.schemas.ts
├── petstore.msw.ts
└── petstore.ts
```

--------------------------------

### Run Orval with Docker and environment variables (Windows Git Bash)

Source: https://orval.dev/docs/installation

Run Orval with environment variables on Windows Git Bash.

```bash
MSYS_NO_PATHCONV=1 docker run --rm \
  -v "$(pwd):/app" \
  -w /app \
  -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
  ghcr.io/orval-labs/orval \
  --config ./orval.config.ts
```

--------------------------------

### Generated Vue Query Composable

Source: https://orval.dev/docs/guides/vue-query

Example of the generated code for a path in an OpenAPI specification, including the query key and the useQuery composable.

```typescript
export const showPetById = (
  petId: string,
  options?: AxiosRequestConfig,
): Promise<AxiosResponse<Pet>> => {
  return axios.get(`/pets/${petId}`, options);
};

export const getShowPetByIdQueryKey = (petId: string) => [`/pets/${petId}`];

export const useShowPetById = <
  TData = AsyncReturnType<typeof showPetById>,
  TError = Error,
>(
  petId: string,
  options?: {
    query?: UseQueryOptions<AsyncReturnType<typeof showPetById>, TError, TData>;
    axios?: AxiosRequestConfig;
  },
) => {
  const { query: queryOptions, axios: axiosOptions } = options ?? {};

  const queryKey = queryOptions?.queryKey ?? getShowPetByIdQueryKey(petId);
  const queryFn = () => showPetById(petId, axiosOptions);

  const query = useQuery<AsyncReturnType<typeof queryFn>, TError, TData>(
    queryKey,
    queryFn,
    {
      enabled: petId !== null && petId !== undefined,
      ...queryOptions,
    },
  );

  return {
    queryKey,
    ...query,
  };
};
```

--------------------------------

### Generated file structure

Source: https://orval.dev/docs/guides/client-with-zod

The resulting directory structure showing the placement of SWR hooks, mocks, and Zod schemas.

```text
src/api/
├── endpoints/
│   └── pets/
│       ├── pets.ts       # SWR hooks
│       ├── pets.msw.ts   # MSW mocks
│       ├── pets.faker.ts # Faker mocks
│       └── pets.zod.ts   # Zod schemas
└── models/
    └── ...
```

--------------------------------

### Run Orval with config file (Windows PowerShell)

Source: https://orval.dev/docs/installation

Run Orval with a configuration file on Windows PowerShell.

```bash
docker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
```

--------------------------------

### Aggregated MSW handlers

Source: https://orval.dev/docs/guides/msw

The generator provides an aggregator function that combines all individual operation handlers for easier setup in your test environment.

```typescript
export const getPetsMock = () => [
  getListPetsMockHandler(),
  getCreatePetsMockHandler(),
  getShowPetByIdMockHandler(),
];
```

--------------------------------

### Specify Input Specification

Source: https://orval.dev/docs/reference/cli

Defines the path or URL to the OpenAPI specification file.

```bash
orval --input ./petstore.yaml
```

--------------------------------

### Unsupported Zod field warning

Source: https://orval.dev/docs/guides/zod

Example of the build warning printed by Orval when an unsupported field is placed within an operation or tag override.

```text
⚠️  override.operations.listPets.zod only supports strict, generate, coerce, preprocess, params, useBrandedTypes, and generateCompanionTypes. Ignoring unsupported field: zod.version.
```

--------------------------------

### Run Orval with Docker and environment variables (macOS / Linux)

Source: https://orval.dev/docs/installation

Run Orval with environment variables for OpenAPI URL and TLS settings on macOS or Linux.

```bash
docker run --rm \
  -v "$(pwd):/app" \
  -w /app \
  -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
  ghcr.io/orval-labs/orval \
  --config ./orval.config.ts
```

--------------------------------

### Configure Faker generator with schemasImportPath

Source: https://orval.dev/docs/reference/configuration/output

Example configuration for orval.config.ts demonstrating the use of schemasImportPath to override the default import path for schema-level faker factories.

```typescript
export default defineConfig({
  petstore: {
    output: {
      target: './libs/client/sdk/generated',
      schemas: {
        path: './libs/data-layer/sdk/generated',
        importPath: '@acme/data-layer/sdk',
      },
      mock: {
        path: './libs/client/sdk/mocks',
        generators: [
          {
            type: 'faker',
            schemas: true,
            schemasImportPath: '@acme/data-layer/sdk/fakers',
          },
        ],
      },
    },
  },
});
```

--------------------------------

### Configure infinite query parameters

Source: https://orval.dev/docs/reference/configuration/output

Demonstrates setting global infinite query parameters and overriding them for specific operations.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        query: {
          useInfinite: true,
          useInfiniteQueryParam: ['page', 'cursor'],
        },
        operations: { 
          listBets: {
            useInfinite: true,
            useInfiniteQueryParam: "cursor.marker",
          }
        }
      },
    },
  },
});
```

--------------------------------

### Generated MCP Project Structure

Source: https://orval.dev/docs/guides/mcp

The generated directory structure includes handler functions, a fetch client, server configuration, and Zod schemas for tool inputs.

```text
src/
├── http-schemas/
│   ├── createPetsBodyItem.ts
│   ├── error.ts
│   ├── index.ts
│   └── pet.ts
├── handlers.ts        # Handler functions returning MCP format
├── http-client.ts     # Generated fetch client
├── server.ts          # MCP tools and server configuration
└── tool-schemas.zod.ts # Zod schemas for tool inputs
```

--------------------------------

### Configure Zod schema generation overrides

Source: https://orval.dev/docs/reference/configuration/output

Example of configuring Zod schema generation options including variant, version, strict mode, and coercion settings in orval.config.ts.

```typescript
export default defineConfig({
  petstore: {
    output: {
      override: {
        zod: {
          variant: 'mini',
          version: 4,
          strict: {
            response: true,
            query: true,
            param: true,
            header: true,
            body: true,
          },
          coerce: {
            query: ['string', 'number', 'boolean'],
          },
          generate: {
            param: true,
            body: true,
            response: true,
            query: true,
            header: true,
          },
          generateEachHttpStatus: true,
          useBrandedTypes: true,
          generateReusableSchemas: true,
          generateDiscriminatedUnion: true,
        },
      },
    },
  },
});
```

--------------------------------

### Specify Output Path

Source: https://orval.dev/docs/reference/cli

Sets the destination path for the generated files.

```bash
orval --output ./api/endpoints/petstoreFromFileSpec.ts
```
Tokens:
Raw