Client API

Spoosh Class

The primary way to create a Spoosh instance with full plugin support. Use this with @spoosh/react hooks.

import { Spoosh } from "@spoosh/core";
import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
]);

Constructor Parameters

Parameter	Type	Required	Description
`baseUrl`	`string`	Yes	Base URL for all API requests
`defaultOptions`	`SpooshOptionsInput`	No	Default options (headers, credentials, transport, etc.)

Type Parameters

new Spoosh<TSchema, TError>(baseUrl, defaultOptions);

Parameter	Description
`TSchema`	Your API schema type
`TError`	Default error type (e.g., `Error`)

Adding Plugins

Use the .use() method to add plugins:

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
  retryPlugin({ retries: 3 }),
]);

With React

src/api/client.ts

import { Spoosh } from "@spoosh/core";
import { createReactSpoosh } from "@spoosh/react";
import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";
import type { ApiSchema } from "./schema";

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
]);

export const { useRead, useWrite, useInfiniteRead } = createReactSpoosh(spoosh);

Request Options

All API calls accept optional request configuration:

const { data } = await api("users").GET({
  query: { page: 1, limit: 10 },
  headers: { Authorization: "Bearer token" },
});

Option	Description
`query`	Query parameters
`body`	Request body (POST, PUT, PATCH). Use `form()` / `json()` / `urlencoded()` wrappers for explicit serialization.
`params`	Path parameters
`headers`	Additional headers

Per-Request Headers

const { data } = await api("users").GET({
  headers: {
    Authorization: `Bearer ${token}`,
    "X-Custom-Header": "value",
  },
});

Default Options

const spoosh = new Spoosh<ApiSchema, Error>("/api", {
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
}).use([cachePlugin(), invalidationPlugin()]);

You can set transport: "xhr" to use XMLHttpRequest instead of the Fetch API. When using XHR transport, TypeScript narrows the available options to only XHR-compatible fields.

const spoosh = new Spoosh<ApiSchema, Error>("/api", {
  transport: "xhr",
  credentials: "include",
}).use([cachePlugin(), invalidationPlugin()]);

createClient

A lightweight client without plugin support. Use this for server-side data fetching in Next.js or simple scripts.

import { createClient } from "@spoosh/core";

const api = createClient<ApiSchema>({
  baseUrl: process.env.API_URL!,
});

const { data } = await api("users").GET();

Option	Type	Description
`baseUrl`	`string`	Base URL for all API requests
`defaultOptions`	`SpooshOptionsInput`	Default options (headers, credentials, transport, etc.)
`middlewares`	`SpooshMiddleware[]`	Request/response middlewares

Next.js Cache Tags

createClient automatically generates Next.js cache tags from the API path:

const api = createClient<ApiSchema>({ baseUrl: process.env.API_URL! });

// Auto-generates: next: { tags: ['posts'] }
await api("posts").GET();

// Auto-generates: next: { tags: ['users', 'users/123', 'users/123/posts'] }
await api("users/:id/posts").GET({ params: { id: 123 } });

This enables automatic cache invalidation with revalidateTag() when using the Next.js plugin.

On this page