Velia

Typed OpenAPI client for TypeScript. Runtime TypeBox validation. TanStack Query bindings. One command to generate, one call to wire.

Velia takes any OpenAPI spec and gives you:

• A fully typed HTTP client. Paths, params, and responses are inferred from the spec.
• Real runtime validation. Requests and responses are checked against TypeBox schemas generated from the same spec. Contract drift throws a VeliaValidationError pointing at the exact field.
• TanStack Query bindings. queryOptions and mutationOptions per endpoint, ready for useQuery and useMutation.
• ky as an optional transport. Plug a configured ky instance for retries, timeouts, and hooks while keeping Velia's types and validation.

You configure it once. Everything else flows from the spec.

📚 Full docs: see docs/ (Mintlify). Highlights:

• Quickstart — 5 minutes from install to a working validated call
• Your first client — hands-on tutorial
• Architecture — how the layers fit
• API reference — every option

Preview the docs locally:

cd docs
nvm use            # picks up Node 22 from .nvmrc; Mintlify CLI requires LTS
npx mintlify dev   # serves on http://localhost:3000

Install

bun add velia
bun add @sinclair/typebox @tanstack/react-query react

The three packages on the second line are peers. Your app controls the versions that ship.

Generate from your spec

bun run generate https://your-api.example.com/openapi.json
# or a local path
bun run generate ./openapi.json

This writes src/endpoints.gen.ts (schemas + typed client) and src/tanstack.client.ts (TanStack Query bindings). Both files are machine output and safe to overwrite.

Use it

import { createVeliaClient } from "velia";

export const velia = createVeliaClient({
  baseUrl: "https://api.example.com",
  auth: () => store.token,
});

const plans = await velia.api.get("/plans", { query: { limit: 10 } });
const plan = await velia.api.get("/plans/{id}", { path: { id: "abc" } });
const created = await velia.api.post("/plans", {
  body: { name: "Pro", amount: 20 },
});

When the server returns a payload that drifts from the spec:

Velia: response from GET /plans (200) did not match the schema:
  - /0/amount: Expected number

The bug is caught at the boundary, with a precise pointer. See Tune runtime validation to toggle it off, route errors to a reporter, or fail open.

Use with ky

Want retries, timeouts, and hooks? Plug a configured ky instance. Velia keeps typing and validation; ky owns transport.

bun add ky

import ky from "ky";
import { createVeliaClientWithKy } from "velia";

const transport = ky.create({
  retry: { limit: 3, methods: ["get"] },
  timeout: 10_000,
  hooks: {
    beforeRequest: [
      async (state) => {
        const token = await getAccessToken();
        if (token) state.request.headers.set("authorization", `Bearer ${token}`);
      },
    ],
  },
});

export const velia = createVeliaClientWithKy(transport, {
  baseUrl: "https://api.example.com",
});

See Use with ky for the full integration notes (retries, hooks, error semantics).

TanStack Query

import { useMutation, useQuery } from "@tanstack/react-query";

const { data } = useQuery(
  velia.query.get("/plans", { query: { limit: 10 } }).queryOptions,
);

const createPlan = useMutation(
  velia.query.mutation("post", "/plans").mutationOptions,
);
createPlan.mutate({ body: { name: "Pro", amount: 20 } });

See Use TanStack Query for prefetch, invalidation, and override patterns.

Errors

| Source | Error | When | | --- | --- | --- | | Schema mismatch | VeliaValidationError | Request params or success body do not match the spec. | | HTTP error status | TypedStatusError | Status in 400-599 range with throwOnStatusError: true (the default). | | Network or fetch | Whatever fetch rejected with | DNS, CORS, offline, abort. |

See Handle errors for branching patterns.

Scripts

| Script | Description | | --- | --- | | bun run generate [spec] | Generate client from an OpenAPI spec (file or URL). Defaults to specs/sample.json. | | bun run typecheck | Type-check src/ and tests/. | | bun run build | Emit dist/. | | bun run test | Run the test suite via Bun's built-in runner. |

Project layout

src/
  endpoints.gen.ts     generated: TypeBox schemas + typed ApiClient
  tanstack.client.ts   generated: TanStack Query bindings
  client.ts            createVeliaClient (one-call setup)
  fetcher.ts           native-fetch fetcher: auth, headers, validation
  validation.ts        runtime TypeBox request/response validation
  errors.ts            VeliaValidationError
  index.ts             public exports
tests/
  client.test.ts       full pipeline via mock fetch
  validation.test.ts   schema lookups + assertValid
  errors.test.ts       error formatting
scripts/
  generate.mjs         typed-openapi runner
  postgenerate.mjs     ts-nocheck + consumer-typing patches
docs/                  Mintlify documentation
specs/                 sample OpenAPI spec

The generated files are marked @ts-nocheck (they are machine output); their exported types still flow to your code, and the hand-written layer in src/ stays fully type-checked. The Generated vs hand-written concept page explains why.

Status

| | | | --- | --- | | Tests | 34 passing across 4 files | | TypeScript | strict, nodenext | | Runtime | Bun, Node 18+, modern browsers, React Native | | License | MIT |