use-fetch-smart

A lightweight, TypeScript-first React data-fetching layer with built-in caching (memory + optional IndexedDB), TTL, retries, and automatic token refresh.

Version: 1.0.13

Install

npm install use-fetch-smart
# or
yarn add use-fetch-smart

This package uses axios and includes optional IndexedDB persistence via idb-keyval when you opt-in to persist on a per-entry basis.

Quick Start

Wrap your app with FetchSmartProvider and provide a refreshToken function for automatic token refresh on 401s. FetchSmartDevtools is safe for development (it is automatically gated in production builds).

import React from 'react';
import { FetchSmartProvider, FetchSmartDevtools } from 'use-fetch-smart';

const refreshToken = async () => {
  const res = await fetch('/auth/refresh');
  if (!res.ok) return null;
  const json = await res.json();
  return json.token;
};

export default function AppRoot() {
  return (
    <FetchSmartProvider config={{ baseURL: 'http://localhost:4000', retryLimit: 3, refreshToken }}>
      <App />
      <FetchSmartDevtools />
    </FetchSmartProvider>
  );
}

Core Hooks

• useGetSmart<T>(url, { cacheTimeMs?, persist?, swr?, skip?, dependencies? }) — returns { data, loading, error, refetch }.

  • cacheTimeMs: TTL in milliseconds.
  • persist: write to IndexedDB (via idb-keyval) in addition to memory.
  • swr: background revalidation (stale-while-revalidate).

• usePostSmart<T, P>(url) — returns { mutate, data, loading, error }.

• usePutSmart<T, P>(url) — same shape as POST.

• useDeleteSmart<T>(url) — returns { mutate, data, loading, error }.

See examples/ for runnable examples.

Cache & Persistence

Layered cache architecture:

• memoryCache: an in-memory Map for instant reads.
• indexedDBCache: optional persistence via idb-keyval when persist: true.
• cacheDriver: internal driver used by hooks — reads from IndexedDB when requested and falls back to memory.

Exports / utilities:

• axiosInstance — the underlying axios instance (advanced use).
• setGlobalToken(token) — set or replace the auth token globally.
• cacheManager — programmatic cache operations (inspect / clear keys).

Example:

useGetSmart('/settings', { cacheTimeMs: 10 * 60_000, persist: true, swr: true });

Devtools

<FetchSmartDevtools /> shows memory + IndexedDB cache contents and TTLs during development. The component is gated and will not render in production builds.

Examples

Includes runnable examples (Express backend + Vite React frontend). See examples/README.md.

Run locally:

cd examples/backend
npm install
node server.js

cd examples/frontend
npm install
npm run dev

Best Practices

• Tune cacheTimeMs per endpoint.
• Use persist: true only for data that benefits from cross-session persistence.
• Invalidate or refetch() after mutations to keep data consistent.

Troubleshooting

• IndexedDB errors: the driver falls back to memory if IndexedDB is unavailable.
• Repeated 401 refreshes: ensure refreshToken returns null on permanent failure.

Package & Version

• Package version: 1.0.13 (see package.json)
• TypeScript definitions included in dist/

Contributing

Contributions welcome — open issues or PRs. Follow standard GitHub workflow.

MIT © 2025