createClient()

Create a fully typed HTTP client from the file kizuna generate writes, using the native fetch API.

Every generated fetch client exports createClient. See the fetch client guide for usage.

pnpm add @kizunajs/fetch@beta

bun add @kizunajs/fetch@beta

npm install @kizunajs/fetch@beta

import { createClient } from './api-client.generated';

The file comes from naming fetchClient({ output }) under clients on defineConfig and running kizuna generate.

Parameters

createClient(config: ClientConfig): Client

Option	Type	Required	Description
`baseUrl`	`string`	Yes	Base URL prepended to every route path
`baseHeaders`	`Record<string, string>`	No	Headers merged into every request
`credentials`	`RequestCredentials`	No	Passed as `credentials` to every `fetch` call
`fetch`	`typeof fetch`	No	Custom fetch implementation (e.g. for testing or a polyfill)
`onRequest`	`(request: OutgoingRequest) => void \| Promise<void>`	No	Callback before each request, receiving the request about to be sent as `{ url, method, headers, route }`. May be async.
`requestContext`	`RequestContext`	*	Header values for your API's request context. Present only when your API declares one, and required when any of its headers is

requestContext values are typed from the declared header schemas, so an optional header stays optional and a coerced one takes the schema's input type. The generated file exports that type as RequestContext.

Returns

createClient returns the Client, mirroring your route groups. Each route becomes a function accepting { params?, query?, body?, headers?, fetchOptions? } and returning a Promise resolving to { status, body, headers }.

params is typed from the route's pathParams schema output when one is declared, matching the server-side handler, otherwise from the :param placeholders in the path.

The response is a discriminated union over the route's declared status codes. Narrow on status to reach the correctly typed body.

Each method carries the route's summary, description, @deprecated and an @example as JSDoc, so an editor shows them at the call site.

Example

When your routes name an identity with identities, send the credential in baseHeaders:

src/lib/api-client.ts

import { createClient } from './api-client.generated';

export const apiClient = createClient({
    baseUrl: 'http://localhost:3000',
    baseHeaders: {
        Authorization: `Bearer ${token}`,
    },
});

const result = await apiClient.users.createUser({
    body: {
        name: 'Alice',
        email: 'alice@example.com',
    },
});

if (result.status === 201) {
    console.log(result.body.id);
} else {
    console.error(result.body.detail);
}

Per-request options

Pass fetchOptions to customize individual requests:

users.ts

const { body } = await apiClient.users.listUsers({
    query: {
        page: 1,
    },
    fetchOptions: {
        signal: AbortSignal.timeout(5000),
    },
});

Named types

The generated file also exports API, the namespace holding every model and every route's Params, Query, Body and Result:

import type { API } from './api-client.generated';

export function UserCard({ user }: { user: API.User }) {
    return <article>{user.name}</article>;
}

See the Fetch client guide for per-request headers, validation errors, refusals, and response type narrowing.

Parameters

Returns

Example

Per-request options

Named types

On this page