Skip to main content

IndexedDB persistence

A product catalog of up to 300 KB per page, cached in IndexedDB. The API answers after two seconds on purpose. After a reload the saved copy appears in a few milliseconds, and the fresh answer replaces it when it arrives.

intermediatepersistencecacheuseFetch
import { useFetch } from "@hyper-fetch/react";
import { useEffect, useRef, useState } from "react";

import { client, getProducts, readSavedEntries } from "./api";

const SIZES = [30, 100, 0];
const pageLoadedAt = Date.now();
const kb = (bytes: number) => `${(bytes / 1024).toFixed(0)} KB`;

type Step = { source: string; ms: number };

const Products = ({ limit }: { limit: number }) => {
// The API waits two seconds, so the copy from IndexedDB clearly shows up first.
const { data, error, loading, responseTimestamp } = useFetch(getProducts.setQueryParams({ limit, delay: 2000 }));
const mountedAt = useRef({ time: Date.now(), perf: performance.now() });
const [steps, setSteps] = useState<Step[]>([]);
const lastSeen = useRef<number>(undefined);

useEffect(() => {
// StrictMode runs effects twice, so every response is recorded once by its timestamp.
if (!responseTimestamp || lastSeen.current === responseTimestamp.getTime()) return;
lastSeen.current = responseTimestamp.getTime();
// Saved before this page load: IndexedDB. Earlier in this page load: memory. Otherwise: the network.
const savedAt = responseTimestamp.getTime();
const source = savedAt < pageLoadedAt ? "IndexedDB" : savedAt < mountedAt.current.time ? "Memory" : "Network";
setSteps((prev) => [...prev, { source, ms: Math.round(performance.now() - mountedAt.current.perf) }]);
}, [responseTimestamp]);

if (error && !data) return <p className="error">Could not load products: {error.message}</p>;

return (
<article>
<ol className="steps">
{steps.map((step, index) => (
<li key={index}>
{step.source === "Network" ? step.source : <mark>{step.source}</mark>} after {step.ms} ms
</li>
))}
{loading && <li aria-busy="true">Revalidating from the network...</li>}
</ol>
<figure className="table-wrap">
<table className="striped">
<tbody>
{data?.products.map((product) => (
<tr key={product.id}>
<td>{product.title}</td>
<td className="muted">{product.category}</td>
<td>${product.price}</td>
</tr>
))}
</tbody>
</table>
</figure>
</article>
);
};

const SavedEntries = () => {
const [saved, setSaved] = useState<{ key: string; bytes: number }[]>([]);
const [quota, setQuota] = useState<number>();

useEffect(() => {
const refresh = () => void readSavedEntries().then(setSaved);
refresh();
navigator.storage?.estimate().then((estimate) => setQuota(estimate.quota));
return client.cache.events.onData(refresh);
}, []);

const total = saved.reduce((sum, entry) => sum + entry.bytes, 0);

return (
<article>
<h6>Saved in IndexedDB: {kb(total)}</h6>
<ul className="list">
{saved.map((entry) => (
<li key={entry.key}>
<code>{entry.key}</code>
<small>{kb(entry.bytes)}</small>
</li>
))}
</ul>
<small className="muted">
Quota for this site: {quota ? `${(quota / 1024 ** 3).toFixed(1)} GB` : "unknown"}. localStorage allows about 5
MB.
</small>
</article>
);
};

export const App = () => {
const [limit, setLimit] = useState(30);

const clearAndReload = async () => {
await client.cache.clear();
window.location.reload();
};

return (
<main className="container">
<hgroup>
<h1>IndexedDB persistence</h1>
<p>Load a catalog, then reload. The saved copy shows up in milliseconds while the slow API is asked again.</p>
</hgroup>
<div className="toolbar">
<div role="group">
{SIZES.map((size) => (
<button
key={size}
type="button"
className={size === limit ? undefined : "outline secondary"}
onClick={() => setLimit(size)}
>
{size === 0 ? "All 194" : size} products
</button>
))}
</div>
<div role="group">
<button type="button" className="secondary" onClick={() => window.location.reload()}>
Reload page
</button>
<button type="button" className="outline" onClick={clearAndReload}>
Clear IndexedDB
</button>
</div>
</div>
<div className="grid-2">
<Products key={limit} limit={limit} />
<SavedEntries />
</div>
</main>
);
};
Run locallynpx tiged BetterTyped/hyper-fetch/examples/react/indexeddb-persistence hyper-fetch-react-indexeddb-persistence && cd hyper-fetch-react-indexeddb-persistence && npm install && npm run dev
What it shows
  1. Cache({ lazyStorage }) writes every cached response to IndexedDB and reads it back when memory has no copy.
  2. CacheAsyncStorageType is four async methods: get, set, keys and delete.
  3. staleTime decides whether a saved entry is still used. Stale entries are not loaded.
  4. A timeline shows where each version of the data came from: IndexedDB, memory or the network.

How it works​

  1. api.ts implements CacheAsyncStorageType with idb-keyval in its own database, so clear() touches only this cache. IndexedDB stores structured clones, so there is no JSON.stringify on every write.

  2. The client passes it as lazyStorage. The main storage stays the default in-memory Map:

    cache: () => new Cache({ lazyStorage: indexedDbStorage }),
  3. When useFetch reads a key that memory does not have, the cache starts an IndexedDB read. If the saved entry has the same version, is fresh and has not expired, it is copied to memory and emitted to the hooks.

  4. The hook can't wait for that read before deciding, so with an empty memory it also sends the request. The result is stale-while-revalidate across reloads: the saved copy first, then the network answer, which is saved again.

  5. getProducts sets staleTime: Time.DAY and cacheTime: Time.WEEK. The defaults are 5 minutes, after which a saved entry would be skipped or removed.

  6. Products compares responseTimestamp with the page load and mount time to label each step. SavedEntries reads IndexedDB on every cache change and shows the size of each entry next to the storage quota from navigator.storage.estimate().

storage or lazyStorage​

localStorage in storageIndexedDB in lazyStorage
SizeAbout 5 MB for the whole siteA share of the disk, often gigabytes
FormatStrings, so JSON.stringify and JSON.parseStructured clones
First renderHas the data, no request neededEmpty, the data arrives a moment later
Blocks main threadOn every read and writeNo

To get both the size of IndexedDB and data on the first render, read the entries once before rendering and pass them as storage, as the offline first example does.

When to use it
  • Large lists, catalogs and documents that do not fit in localStorage.
  • Apps that show the last data at once and refresh it in the background.

Summary

An async storage passed as lazyStorage saves every cached response to IndexedDB. After a reload the cache reads it back on demand, shows it right away, and the hook refreshes it from the network.