@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();

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

@wyattjoh/astro-cache

Get started

Weekly DownloadsAcross all versions

Versions

Dependencies (2)

Peer Dependency (1)

Keywords

Maintainers

Readme