Multiple instances

When you need more than one instance

Each Kweri instance is bound to a single baseURL and owns an isolated cache. If your app talks to several APIs, use one instance per API — that’s the correct design, not just a convenience:

Cache keys are method + path + params — the baseURL is not part of the key. So two APIs that both expose /users would collide in a shared cache. Separate instances give you correct isolation, plus independent eviction and per-API staleTime/cacheTime.

The only downside is repeated config. The factory helpers remove it.

`createKweriClients` (named map)

Create several named instances that share defaults. Each entry is a baseURL string (shorthand) or full per-client options:

import { createKweriClients, presets } from 'kweri'

export const { main, stocks } = createKweriClients(
  {
    main: { baseURL: 'https://api.example.com', enableDevTools: true },
    stocks: 'https://stocks.example.com', // shorthand
  },
  presets.spa, // shared defaults
)

It returns the instances keyed by name, plus a non-enumerable destroyAll():

const clients = createKweriClients({ a: A_URL, b: B_URL })
clients.destroyAll() // tears down every instance

destroyAll is a reserved key — don’t name a client destroyAll.

`createKweriFactory` (low-level primitive)

createKweriClients is built on this. It captures defaults and returns instances when invoked, so you control lifetime:

import { createKweriFactory } from 'kweri'

const createApi = createKweriFactory({ staleTime: 30_000, cacheTime: 5 * 60_000 })

export const kweri = createApi('https://api.example.com', { enableDevTools: true })
export const stocks = createApi('https://stocks.example.com')

Presets

Opinionated default profiles for common project types. GC is automatic (honors cacheTime in the browser), so presets don’t set gcInterval.

import { presets } from 'kweri'

presets.spa      // { staleTime: 30_000,  cacheTime: 5m,  maxRetries: 2 }
presets.ssr      // { staleTime: 60_000,  maxRetries: 0 }   — create per request
presets.mobile   // { staleTime: 60_000,  cacheTime: 30m, maxRetries: 3 }
presets.realtime // { staleTime: 0,       cacheTime: 30s, maxRetries: 1 }

Pass one as the defaults and override per client as needed.

Per-environment patterns

Because the factory returns instances on call, the application chooses the instantiation scope:

SPA
SSR / RSC
Multi-tenant / dynamic

Module-level singletons are fine — one cache for the app’s lifetime.

export const { main, stocks } = createKweriClients(map, presets.spa)

Never share a singleton cache across requests — it bleeds one user’s data into another’s. Create instances per request and provide them via context.

export const makeClients = () => createKweriClients(map, presets.ssr)
// call makeClients() once per request; destroyAll() when the request ends

baseURL isn’t known at import time — instantiate lazily and tear down on tenant switch.

const make = createKweriFactory(presets.spa)
const cache = new Map<string, Kweri>()
export const tenantApi = {
  get: (id: string) => cache.get(id) ?? cache.set(id, make(urlFor(id))).get(id)!,
  reset: () => { cache.forEach(k => k.destroy()); cache.clear() },
}

Path hooks per instance

Each API has its own generated EndpointByMethod (its own types), so path hooks are bound per (instance, EndpointByMethod) pair — you can’t share one useGet across APIs. Create a hook set per API and group them:

import { useSyncExternalStore } from 'react'
import { createReactPathHooks } from 'kweri'
import { EndpointByMethod as MainEndpoints } from '@/api/main/client'
import { EndpointByMethod as StocksEndpoints } from '@/api/stocks/client'
import { main, stocks } from '@/lib/kweri'

export const api = {
  main: createReactPathHooks(useSyncExternalStore, main, MainEndpoints),
  stocks: createReactPathHooks(useSyncExternalStore, stocks, StocksEndpoints),
}

Each group is fully typed against its own API:

const { data } = api.main.useGet('/users', {})          // typed by MainEndpoints
const create = api.stocks.usePost('/orders')            // typed by StocksEndpoints

Generate each API into its own --out dir (kweri-gen <main-spec> --out src/api/main, kweri-gen <stocks-spec> --out src/api/stocks) so their EndpointByMethod maps stay separate.

Per-API auth

Auth differs per API, so it’s a per-client fetcher, not a shared default:

import { createKweriClients, type Fetcher } from 'kweri'

const withAuth = (getToken: () => string): Fetcher =>
  ({ method, url, body }) =>
    fetch(url, {
      method,
      headers: {
        Authorization: `Bearer ${getToken()}`,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    })

export const { main, stocks } = createKweriClients(
  {
    main:   { baseURL: MAIN,   fetcher: withAuth(getUserToken) },
    stocks: { baseURL: STOCKS, fetcher: withAuth(getServiceToken) },
  },
  presets.spa,
)

DevTools with multiple instances

Enabling enableDevTools on several instances is safe — they share one panel with an instance switcher in the header (no stacked overlays). Each instance appears in the switcher labelled by its baseURL, or by devtools.label if set:

createKweriClients({
  main:   { baseURL: MAIN,   enableDevTools: true },
  stocks: { baseURL: STOCKS, enableDevTools: true, devtools: { label: 'Stocks API' } },
})

The first instance to enable devtools mounts the panel, so panel-level options like position come from that instance. The panel unmounts automatically when the last instance is destroyed.

Getting Started

Core Concepts

Core API

Framework Adapters

CLI

Guides

Advanced

API Reference

Multiple instances

When you need more than one instance

`createKweriClients` (named map)

`createKweriFactory` (low-level primitive)

Presets

Per-environment patterns

Path hooks per instance

Per-API auth

DevTools with multiple instances

​When you need more than one instance

​createKweriClients (named map)

​createKweriFactory (low-level primitive)

​Presets

​Per-environment patterns

​Path hooks per instance

​Per-API auth

​DevTools with multiple instances

When you need more than one instance

`createKweriClients` (named map)

`createKweriFactory` (low-level primitive)

Presets

Per-environment patterns

Path hooks per instance

Per-API auth

DevTools with multiple instances