@wyattjoh/astro-cache

Astro integration providing disk-backed SWR (stale-while-revalidate) and memo caching utilities powered by flat-cache and stale-while-revalidate-cache.

Installation

npm install @wyattjoh/astro-cache
# or
bun add @wyattjoh/astro-cache
# or
pnpm add @wyattjoh/astro-cache

Requires astro ^5.0.0 as a peer dependency.

Setup

Add the integration to your astro.config.ts:

import { defineConfig } from "astro/config";
import astroCache from "@wyattjoh/astro-cache";

export default defineConfig({
  integrations: [astroCache()],
});

Options

| Option | Type | Default | Description | | ------------- | --------- | ------- | ------------------------------------------------ | | devCaching | boolean | false | Enable caching during astro dev. When omitted or false, swr() and memo() become transparent passthroughs in dev mode so you always see fresh data. Caching is always active during build and preview. |

// Enable caching in dev mode
astroCache({ devCaching: true });

Environment Variables

The integration registers the following environment variables via Astro's env schema (all server-only, with sensible defaults):

| Variable | Type | Default | Description | | ------------------------------ | --------- | ---------------------------------- | ------------------------------------------ | | ASTRO_CACHE_ENABLED | boolean | true (false in dev) | Whether caching is active (set via devCaching option) | | ASTRO_CACHE_DIR | string | node_modules/.cache/astro-cache | Directory for flat-cache disk persistence | | ASTRO_CACHE_MIN_TIME_TO_STALE| number | 1800000 (30 min) | SWR: min ms before data is considered stale | | ASTRO_CACHE_MAX_TIME_TO_LIVE | number | 604800000 (7 days) | SWR: max ms before data must be refetched |

API

Import the cache utilities from @wyattjoh/astro-cache/cache:

import { swr, memo, clearAllCaches } from "@wyattjoh/astro-cache/cache";

swr(fn, options)

Wraps an async function with SWR caching. Stale data is served instantly while fresh data is fetched in the background. Backed by flat-cache for disk persistence.

const getUser = swr(
  async (id: string) => {
    const res = await fetch(`/api/users/${id}`);
    return res.json();
  },
  { name: "users", max: 100 }
);

const user = await getUser("123");

// Clear only this cache:
getUser.clear();

Options:

• name (required) — unique cache identifier
• max — LRU size limit (0 = unlimited)

memo(fn, options)

Wraps an async function with a simple cache backed by flat-cache. Use for non-serializable data (e.g. ArrayBuffer) or cases where SWR is unnecessary.

const getConfig = memo(
  async () => {
    const res = await fetch("/api/config");
    return res.json();
  },
  { name: "config" }
);

const config = await getConfig();

// Clear only this cache:
getConfig.clear();

Options:

• name (required) — unique cache identifier
• max — LRU size limit (0 = unlimited)
• ttl — time-to-live in ms (defaults to ASTRO_CACHE_MIN_TIME_TO_STALE)
• persist — write to disk (default: true)

clearAllCaches()

Clears all caches created by swr and memo.

clearAllCaches();

Clearing Individual Caches

Both swr and memo return functions with a .clear() method that removes all entries from that specific cache (including its disk-persisted data). Use this when you need to invalidate a single cache without affecting others.

const getUser = swr(async (id: string) => { /* ... */ }, { name: "users" });
const getConfig = memo(async () => { /* ... */ }, { name: "config" });

// Clear only the users cache:
getUser.clear();

// Clear only the config cache:
getConfig.clear();

// Or clear everything at once:
clearAllCaches();

License

MIT