Initialize the client

The backend client is created a little differently depending on where your server code runs, but the client surface after that point is the same. The framework adapters give you wachtClient() and createWachtServerClient(), while the standalone backend package gives you WachtClient, initClient(), and the global client store helpers.

Usage

The following example shows a basic usage of the backend client from @wacht/nextjs/server.

import { wachtClient } from '@wacht/nextjs/server';export default async function Example() {  const client = await wachtClient();  const health = await client.health.healthCheck();  return <pre>{JSON.stringify(health, null, 2)}</pre>;}

Signature

type WachtServerClientOptions = {  apiKey?: string;  apiUrl?: string;  timeout?: number;  headers?: Record<string, string>;  fetch?: typeof fetch;  name?: string;};declare function createWachtServerClient(options?: WachtServerClientOptions): WachtServerClient;declare function wachtClient(options?: WachtServerClientOptions): Promise<WachtServerClient>;

Return value

›

apiKey?: string | undefined;

Explicit API key. When omitted in the framework adapters, the client falls back to `WACHT_API_KEY`.

›

apiUrl?: string | undefined;

Override the backend API base URL.

›

timeout?: number | undefined;

Request timeout in milliseconds.

›

headers?: Record<string, string> | undefined;

Extra headers to attach to every request.

›

fetch?: typeof fetch | undefined;

Custom fetch implementation for runtimes that need one.

›

name?: string | undefined;

Optional logical client name. In the standalone backend package, a named client can also be registered into a `WachtClientStore`.

›

createClientStore?: () => WachtClientStore | undefined;

Create an explicit client registry when you want to keep several named backend clients alive at once.

›

initClient?: (config: WachtConfig) => void | undefined;

Initialize the global backend client used by the standalone helper modules in `@wacht/backend`.

›

getClient?: () => WachtClient | undefined;

Read the global backend client. This throws until `initClient()` has run.

›

isClientInitialized?: () => boolean | undefined;

Check whether the global backend client has already been initialized.

Framework adapters

In Next.js, React Router, and TanStack Router, the server package exposes createWachtServerClient() and wachtClient(). createWachtServerClient() always creates a fresh backend client. wachtClient() caches and reuses a default client when you call it without options.

That makes wachtClient() the right default for most server code paths, while createWachtServerClient() is the better fit when you need an alternate API key, a different base URL, or request-specific headers.

Standalone backend usage

In the standalone backend package, you can instantiate new WachtClient(...) directly, or you can initialize a global client with initClient() and then use the exported resource modules through getClient() behind the scenes.

That global style is useful in scripts and long-running JavaScript services where you want one process-wide client. If you need more than one backend client at the same time, use createClientStore() and register named clients instead of mutating the global singleton.

Runtime requirements

The backend client expects a JavaScript runtime with fetch, or a fetch implementation passed explicitly through config. That keeps the same client usable across Node.js, Bun, edge-style runtimes, and other server-side JavaScript environments.

wachtClient() in the framework adapters resolves WACHT_API_KEY for you when you do not pass apiKey, and it throws early if no API key can be found. The cached path is only used when you call it without options.

Examples

Create a named client with explicit config

import { createWachtServerClient } from '@wacht/nextjs/server';export default async function Example() {  const client = createWachtServerClient({    apiKey: process.env.WACHT_API_KEY,    timeout: 10_000,    name: 'admin-console',  });  const users = await client.users.listUsers({ limit: 5 });  return <pre>{JSON.stringify(users.data, null, 2)}</pre>;}

Initialize the standalone backend package once

import { initClient, users } from '@wacht/backend';initClient({  apiKey: process.env.WACHT_API_KEY!,});export async function listRecentUsers() {  return users.listUsers({ limit: 10 });}

Keep multiple named backend clients

import { WachtClient, createClientStore } from '@wacht/backend';const store = createClientStore();const primary = new WachtClient({  apiKey: process.env.WACHT_PRIMARY_API_KEY!,  name: 'primary',  store,});const staging = new WachtClient({  apiKey: process.env.WACHT_STAGING_API_KEY!,  baseUrl: 'https://staging-api.wacht.io',  name: 'staging',  store,});export async function compareHealth() {  const primaryHealth = await primary.health.healthCheck();  const stagingHealth = await store.get('staging').health.healthCheck();  return { primaryHealth, stagingHealth };}