Introduction
A type-safe API client with a powerful plugin system
Spoosh is a lightweight, type-safe API client with a powerful plugin system. It provides a clean, intuitive way to define API schemas and make HTTP requests with full TypeScript support.
Key Features
- Type-Safe Schema Definition - Define your API once, get autocomplete and type checking everywhere
- Plugin System - Extend functionality with caching, retry, polling, optimistic updates, and more
- Framework Bindings - Hooks for React, with more frameworks coming soon
- Server Adapters - First-class support for Hono with automatic type inference
- Cache Invalidation - Automatic tag-based cache invalidation after mutations
- Next.js Integration - Server-side cache revalidation with App Router
Quick Example
import { createSpoosh } from "@spoosh/core";
import { createReactSpoosh } from "@spoosh/react";
import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";
// Define your API schema
type ApiSchema = {
users: {
$get: Endpoint<User[]>;
$post: Endpoint<User, CreateUserBody>;
};
};
// Create the client with plugins
const spoosh = createSpoosh<ApiSchema>({
baseUrl: "/api",
plugins: [
cachePlugin({ staleTime: 5000 }),
invalidationPlugin(), // Auto-refresh queries after mutations
],
});
// Export hooks
export const { useRead, useWrite } = createReactSpoosh(spoosh);// Use in your components
function UserList() {
const { data, loading, error } = useRead((api) => api.users.$get());
if (loading) return <Spinner />;
if (error) return <Error message={error.message} />;
return (
<ul>
{data?.map((user) => (
<li key={user.id}>{user.name}</li>
))}
</ul>
);
}Packages
| Package | Description |
|---|---|
@spoosh/core | Core client and plugin system |
@spoosh/react | React bindings (useRead, useWrite, useInfiniteRead) |
@spoosh/hono | Hono type adapter |
@spoosh/openapi | OpenAPI spec generator |
Plugins
| Plugin | Description |
|---|---|
@spoosh/plugin-cache | Response caching with stale time |
@spoosh/plugin-invalidation | Auto-refresh queries after mutations (recommended) |
@spoosh/plugin-retry | Automatic retry with configurable attempts |
@spoosh/plugin-optimistic | Optimistic updates with rollback |
@spoosh/plugin-polling | Automatic polling at intervals |
@spoosh/plugin-debounce | Request debouncing |
@spoosh/plugin-throttle | Request throttling |
@spoosh/plugin-deduplication | Prevents duplicate in-flight requests |
@spoosh/plugin-prefetch | Preload data before needed |
@spoosh/plugin-refetch | Refetch on focus/reconnect |
@spoosh/plugin-initial-data | Show data before fetch completes |
@spoosh/plugin-nextjs | Next.js server revalidation |
@spoosh/plugin-debug | Debug logging |