createClient() | Kizuna.js

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

The generated file imports nothing, so calling it needs no package installed.

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 }`, where `route` is the route's table entry. 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 when one is declared, otherwise from the :param placeholders in the path. A request type reads what the caller sends, so a schema that transforms its value takes the value before the transform.

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:

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:

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. The config's namespace option calls it something else:

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.