---

name: add-caching description: Add client-side caching with stale-while-revalidate strategy. Use when optimizing page load performance or reducing server requests.

Add Caching

Adds client-side caching using remix-client-cache with a stale-while-revalidate (SWR) strategy.

When to Use

• Improving page load performance
• Reducing server requests for frequently accessed data
• Caching loader data across navigations
• User asks to "add caching", "improve performance", or "cache data"

How SWR Works

1. Returns cached (stale) data immediately
2. Refreshes data in the background
3. Hot-swaps updated data when available

Step 1: Configure Global Storage

Location: app/entry.client.tsx

Copyimport { configureGlobalCache } from "remix-client-cache";

// Use localStorage for persistent cache
configureGlobalCache(() => localStorage);

// Or sessionStorage (cleared when tab closes)
configureGlobalCache(() => sessionStorage);

Step 2: Create Cached Client Loader

Copyimport { createClientLoaderCache } from "remix-client-cache";
import type { Route } from "./+types/my-route";

export async function loader({ request }: Route.LoaderArgs) {
    const data = await fetchData();
    return { data };
}

// Generate cached client loader
export const clientLoader = createClientLoaderCache({
    loader,
    // Optional: custom cache key
    key: (args) => `products-${args.params.id}`,
});

// Enable client loader hydration
clientLoader.hydrate = true;

Step 3: Use Cached Data in Component

Option A: useCachedLoaderData Hook

Copyimport { useCachedLoaderData } from "remix-client-cache";
import type { Route } from "./+types/my-route";

export default function MyRoute() {
    const data = useCachedLoaderData<typeof loader>();

    return (
        <div>
            <h1>{data.title}</h1>
        </div>
    );
}

Option B: CacheRoute Wrapper

Copyimport { CacheRoute } from "remix-client-cache";
import type { Route } from "./+types/my-route";

export default function MyRoute() {
    return (
        <CacheRoute>
            {(data) => (
                <div>
                    <h1>{data.title}</h1>
                </div>
            )}
        </CacheRoute>
    );
}

Cache Invalidation

After Mutations

Copyimport { decacheClientLoader } from "remix-client-cache";
import type { Route } from "./+types/my-route";

export async function clientAction({ request }: Route.ClientActionArgs) {
    const result = await submitForm(request);

    // Clear the cache for this route
    await decacheClientLoader();

    return result;
}

Manual Invalidation

Copyimport { invalidateCache, useCacheInvalidator } from "remix-client-cache";

// Direct invalidation
await invalidateCache("my-cache-key");
await invalidateCache(["key1", "key2"]);

// Hook-based invalidation
function RefreshButton() {
    const invalidate = useCacheInvalidator();

    return (
        <button onClick={() => invalidate("my-cache-key")}>
            Refresh
        </button>
    );
}

Manual Cache Wrapper

For more control:

Copyimport { cacheClientLoader } from "remix-client-cache";
import type { Route } from "./+types/my-route";

export async function clientLoader(args: Route.ClientLoaderArgs) {
    return cacheClientLoader(args, {
        key: `user-${args.params.id}`,
        adapter: () => sessionStorage,
    });
}

clientLoader.hydrate = true;

Storage Options

Best Practices

1. Configure storage early - Set up in entry.client.tsx before hydration
2. Use meaningful cache keys - Include dynamic parameters: products-${productId}
3. Invalidate after mutations - Always clear cache in clientAction
4. Set hydrate = true - Enable proper hydration for cached data
5. Consider data freshness - Not all data should be cached

When NOT to Cache

• Real-time data that changes frequently
• User-specific sensitive data (with localStorage)
• Data that must always be fresh
• Small, fast API responses

Anti-Patterns

• Forgetting to invalidate cache after mutations
• Using localStorage for sensitive data
• Caching without considering data freshness
• Not setting hydrate = true on clientLoader

Full Reference

See .github/instructions/client-side-caching.instructions.md for comprehensive documentation.