Migration Guide

This guide helps you migrate from other data fetching libraries to SoulCache.

Upgrading v1.1.0 → v1.1.1

v1.1.1 is a security patch. The public API is unchanged and no persisted-payload migration is required. Review two behavior changes:

1. `dehydrate()` no longer includes `error.stack`

Dehydrated error entries previously carried error.stack, which can leak internal file paths to clients in SSR flows. Stacks are now omitted by default; message and name are always preserved.

// Opt back in for server-side debugging only:
const state = dehydrate(queryClient, { includeStack: true });

2. `sha-384` / `sha-512` / `md5` checksum labels can no longer be written

These labels were never implemented (every label previously produced the same non-cryptographic 32-bit djb2 value). Writing with them now throws SerializationError. sha-256 is now a real FIPS 180-4 SHA-256 digest (64-hex), and legacy payloads from 1.0.0/1.1.0 remain readable under all labels.

// Recommended:
const serializer = new JsonSerializer({ checksum: 'sha-256' });
// or keep the fast default:
const serializer = new JsonSerializer();

From React Query

Setup

// Before (React Query)
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
// After (SoulCache)
import { SoulCacheProvider } from '@soulcache/react';

Hooks

// Before (React Query)
import { useQuery } from '@tanstack/react-query';
 
// After (SoulCache)
import { useQuery } from '@soulcache/react';

Query Options

// Before (React Query)
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  staleTime: 5 * 60 * 1000,
  retry: 3,
});
 
// After (SoulCache) — configure via QueryClient
// Note: SoulCache does not apply a global `retry` option in the current
// release. Query-level retry is handled internally; for mutations use
// `MutationEntry.mutateWithRetry()`.
const client = new QueryClient();
 
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
});

From SWR

Setup

// Before (SWR)
import useSWR from 'swr';
 
// After (SoulCache)
import { useQuery } from '@soulcache/react';

Fetcher

// Before (SWR)
const { data } = useSWR('/api/users', fetcher);
 
// After (SoulCache)
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then(r => r.json()),
});

Key Differences

Feature	React Query	SWR	SoulCache
Runtime deps	0	0	0
Bundle size (min+gzip)	~12KB	~4KB	~16KB
TypeScript	Good	Good	Excellent
Plugin system	Yes	No	Internal (roadmap)
DevTools	Yes	No	Yes

Migration Checklist

Migration Steps

Install @soulcache/core and @soulcache/react
Replace QueryClient imports
Replace hook imports
Update query options
Test all queries
Update DevTools

Migration Guide

On this page