fetch-mock-cache

library2.3.1jsnpmunverified

Caching mock fetch implementation (v2.3.1, 2023, MIT) that automatically caches real HTTP responses on first call and replays them on subsequent calls. Supports node, bun, deno and testing frameworks like jest, vitest, node:test. Key differentiator: no manual mock writing – just run real fetch once, cache auto-saved to filesystem (or custom stores). Used by yahoo-finance2 for 1400+ API calls in <1s. Active development with semantic releases. Alternative to nock, msw, jest-fetch-mock that offers zero-config caching and team/CI cache sharing via committed fixtures.

testing

npm install fetch-mock-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-MOCK-CACHE

fetch-mock-cache

testingjavascriptv2.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createFetchCache

✓ import createFetchCache from 'fetch-mock-cache'

✗ const createFetchCache = require('fetch-mock-cache')

Package is ESM-only; default export is createFetchCache. CJS require will fail.

Store (filesystem store)

✓ import FsStore from 'fetch-mock-cache/stores/fs'

✗ import { FsStore } from 'fetch-mock-cache/stores/fs'

Filesystem store is default export from 'fetch-mock-cache/stores/fs', not a named export.

type FetchCache

✓ import type { FetchCache } from 'fetch-mock-cache'

Type import only, for TypeScript users. The type is not a value export.

Shows basic setup: createFetchCache with filesystem store, mock global fetch, then first call misses (real request), second hits cache.

import createFetchCache from 'fetch-mock-cache'; import FsStore from 'fetch-mock-cache/stores/fs'; const fetchCache = createFetchCache({ Store: FsStore }); // Mock global fetch globalThis.fetch = fetchCache; async function main() { // First call hits real API; second returns cached const url = 'https://jsonplaceholder.typicode.com/todos/1'; for (let i = 0; i < 2; i++) { const response = await fetch(url); const data = await response.json(); console.log('Cache status:', response.headers.get('X-FMC-Cache')); console.log('Data:', data); } } main();

Debug

Known issues

breakingv1 (jest-fetch-mock-cache) to v2 migration: package renamed, import changed, API breaking (createFetchCache instead of default export with options object).

fix

Upgrade to v2: see MIGRATING.md; replace 'jest-fetch-mock-cache' with 'fetch-mock-cache' and use new API.

affects: <2.0.0

deprecatedUsing jest-fetch-mock-cache (v1) is deprecated; all development continues on fetch-mock-cache v2+.

fix

Migrate to fetch-mock-cache v2 as above.

affects: <2.0.0

gotchaCache store must be imported from subpath (e.g., 'fetch-mock-cache/stores/fs') – NOT from the main package.

fix

Use correct import: import FsStore from 'fetch-mock-cache/stores/fs'.

affects: >=2.0.0

gotchaESM-only package – do NOT use require() as it will throw 'ERR_REQUIRE_ESM'.

fix

Use import syntax. If using CommonJS, dynamic import: import('fetch-mock-cache').then(m => ...).

affects: >=2.0.0

gotchaOn first run, real HTTP request is made; ensure network is available or test may fail.

fix

Run tests with network access at least once to generate cache, or pre-populate fixture files.

affects: >=2.0.0

gotchaX-FMC-Cache header is only added when using the mock; real fetch does not have it.

fix

Only check for this header in tests using mocked fetch.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /node_modules/fetch-mock-cache/... not supported.

Using CommonJS require() on ESM-only package.

fix

Use import syntax or dynamic import().

TypeError: createFetchCache is not a function

Incorrectly destructuring default export or using named import.

fix

Use: import createFetchCache from 'fetch-mock-cache'; (without curly braces).

Cannot find module 'fetch-mock-cache/stores/fs'

Missing dependency or incorrect path (e.g., v1 had different store path).

fix

Ensure fetch-mock-cache v2+ is installed, and import from 'fetch-mock-cache/stores/fs' (not 'stores/fs').

Error: fetch is not defined

Running in Node.js <18 without global fetch polyfill.

fix

Use Node.js 18+ or install node-fetch and polyfill global fetch.

Upgrade

Version history

2.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gadicc/fetch-mock-cache ↗

packagefetch-mock-cache ↗

homepagehttps://github.com/gadicc/fetch-mock-cache#readme ↗