Plugin System

Plugins are the heart of Spoosh. They extend the core functionality with features like caching, automatic retries, cache invalidation, and optimistic updates.

Installing Plugins

Each plugin is a separate package:

npm install @spoosh/plugin-cache @spoosh/plugin-invalidation @spoosh/plugin-retry

Using Plugins

Pass plugins to createSpoosh:

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

const plugins = [
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(), // Auto-refresh queries after mutations
  retryPlugin({ retries: 3 }),
];

const spoosh = createSpoosh<ApiSchema, Error, typeof plugins>({
  baseUrl: "/api",
  plugins,
});

Available Plugins

Essential

Plugin	Package	Description
Cache	`@spoosh/plugin-cache`	Response caching with configurable stale time
Invalidation	`@spoosh/plugin-invalidation`	Auto-invalidate queries after mutations
Deduplication	`@spoosh/plugin-deduplication`	Prevent duplicate concurrent requests
Retry	`@spoosh/plugin-retry`	Automatic retry on failure

Data Management

Plugin	Package	Description
Optimistic	`@spoosh/plugin-optimistic`	Instant UI updates with automatic rollback
Initial Data	`@spoosh/plugin-initial-data`	Provide initial data for queries
Prefetch	`@spoosh/plugin-prefetch`	Preload data before it's needed

Request Control

Plugin	Package	Description
Polling	`@spoosh/plugin-polling`	Automatic periodic refetching
Refetch	`@spoosh/plugin-refetch`	Refetch on window focus/network reconnect
Debounce	`@spoosh/plugin-debounce`	Delay requests until input stops changing
Throttle	`@spoosh/plugin-throttle`	Limit request frequency

Framework Integration

Plugin	Package	Description
Next.js	`@spoosh/plugin-nextjs`	Server-side cache revalidation
Debug	`@spoosh/plugin-debug`	Development logging

Recommended Setup

For most applications, we recommend this plugin combination:

import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";
import { deduplicationPlugin } from "@spoosh/plugin-deduplication";
import { retryPlugin } from "@spoosh/plugin-retry";
import { refetchPlugin } from "@spoosh/plugin-refetch";

const plugins = [
  cachePlugin({ staleTime: 5000 }),
  deduplicationPlugin(),
  invalidationPlugin(),
  retryPlugin({ retries: 3 }),
  refetchPlugin({ refetchOnFocus: true }),
];

This gives you:

Caching - Avoid redundant network requests
Deduplication - Prevent duplicate requests when multiple queries invalidate at once
Auto-invalidation - Queries refresh automatically after mutations
Retry - Automatic recovery from transient failures
Refetch - Fresh data when users return to your app

Plugin Order

Most plugins work in any order. The exceptions are:

cachePlugin - should be registered early to check cache before making requests
throttlePlugin - should be registered last to block all requests including force fetches

const plugins = [
  cachePlugin({ staleTime: 5000 }), // Early - check cache first
  deduplicationPlugin(),
  invalidationPlugin(),
  retryPlugin(),
  throttlePlugin(), // Last - blocks everything
];

Tip: The deduplicationPlugin is especially useful with invalidationPlugin. When a mutation invalidates multiple queries with overlapping tags, deduplication ensures only one network request is made per unique endpoint.

Per-Request Options

Most plugins support per-request overrides:

// Override cache time for this query
useRead((api) => api.users.$get(), { staleTime: 60000 });

// Disable retries for this query
useRead((api) => api.health.$get(), { retries: false });

// Custom polling interval
useRead((api) => api.notifications.$get(), { pollingInterval: 5000 });

On this page