Registry / storage / axios-cache-interceptor

axios-cache-interceptor

library1.12.0jsnpmunverified

A cache interceptor for Axios that transparently caches HTTP responses in memory (or custom storage) to reduce network requests. Version 1.12.0, actively maintained with weekly releases. Supports per-request TTL, cache invalidation, response cloning, and custom storage backends like localStorage. Ships TypeScript definitions. Notable differentiators: works as an Axios interceptor (not a wrapper), provides cached property on responses, and supports fine-grained cache control per request. Requires Axios 1.x as a peer dependency.

storage

npm install axios-cache-interceptor

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AXIOS-CACHE-INTERC

axios-cache-interceptor

storagejavascriptv1.12.0

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.

setupCache

✓ import { setupCache } from 'axios-cache-interceptor'

✗ const setupCache = require('axios-cache-interceptor').setupCache

ESM package; CommonJS requires .default or destructuring via require('axios-cache-interceptor').default

setupCache (default import)

✓ import setupCache from 'axios-cache-interceptor'

✗ const setupCache = require('axios-cache-interceptor')

Default export is also available as a function; but named import 'setupCache' is preferred for clarity

buildStorage

✓ import { buildStorage } from 'axios-cache-interceptor'

✗ import buildStorage from 'axios-cache-interceptor'

buildStorage is a named export, not a default export

AxiosCacheInstance

✓ import type { AxiosCacheInstance } from 'axios-cache-interceptor'

✗ import { AxiosCacheInstance } from 'axios-cache-interceptor'

AxiosCacheInstance is a type, so use import type in TypeScript

Demonstrates basic setup with custom storage and TTL, default memory storage, and how to check if response was cached via the `.cached` property.

import Axios from 'axios'; import { setupCache, buildStorage } from 'axios-cache-interceptor'; const instance = Axios.create(); const cachedAxios = setupCache(instance, { storage: buildStorage({ async find(key) { /* custom lookup */ }, async set(key, value) { /* custom store */ }, async remove(key) { /* custom delete */ } }), ttl: 1000 * 60 * 5, // 5 minutes }); async function fetchData() { const res1 = await cachedAxios.get('https://api.example.com/data'); console.log(res1.cached); // false (first request) const res2 = await cachedAxios.get('https://api.example.com/data'); console.log(res2.cached); // true (served from cache) } fetchData();

Debug

Known issues

breakingIn v1.0, the API changed from `setupCache(axios, options?)` to `setupCache(instance, options?)` where the first argument must be an Axios instance, not a default Axios export.

fix

Create an instance with axios.create() and pass it to setupCache.

affects: < 1.0

breakingIn v1.0, the default storage type changed from in-memory Map to a Storage interface. Custom storage built for v0.x will not work.

fix

Use buildStorage() or implement the Storage interface (find, set, remove methods).

affects: < 1.0

deprecatedThe `cache` property on the Axios request config is deprecated in favor of `id`, `cache: true/false` and `override`. Use `cache: { ttl: number, interpretHeader: boolean }` instead.

fix

Pass cache config as an object: setupCache(instance, { cache: { ttl: 60000 } }) or per request: axios.get(url, { cache: { ttl: 30000 } })

affects: >=1.0

gotchaWhen using `setupCache` with an existing Axios instance that already has interceptors, the interceptor order matters: the cache interceptor must be registered before response interceptors that modify data, otherwise cached responses may skip those interceptors.

fix

Call setupCache before adding other interceptors, or use the `interceptor` option to set explicit order.

affects: >=1.0

gotchaThe `.cached` property on response is only available if you use the setupCache wrapper; calling axios directly (without the cached instance) will not have this property.

fix

Always use the instance returned by setupCache for all requests that need caching.

affects: >=1.0

gotchaBy default, the cache respects the `Cache-Control` header if `interpretHeader: true` is set. Without it, the TTL you specify or the default TTL (1000ms) applies. This can cause stale data.

fix

Set `interpretHeader: true` in cache options to use server-side cache headers, or set an appropriate TTL.

affects: >=1.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'setupCache')

Using CommonJS require without destructuring the default export.

fix

Use `const { setupCache } = require('axios-cache-interceptor');` or use ESM import.

Error: Could not find Axios instance. Please provide a valid Axios instance.

Passing the default axios module (e.g., `setupCache(axios)`) rather than an instance created with `axios.create()`.

fix

Create an instance: const instance = axios.create(); then call setupCache(instance).

TypeError: storage.find is not a function

Custom storage does not implement the required `find`, `set`, and `remove` methods correctly.

fix

Ensure your storage object has all three methods: find(key), set(key, value), remove(key). Use buildStorage() to create one.

Warning: response.cached is undefined

Using the original axios instance instead of the one returned by setupCache.

fix

Use the instance returned by setupCache for requests: `const cachedAxios = setupCache(instance); cachedAxios.get(...)`.

Upgrade

Version history

1.12.0latest on npm

Audit

Dependencies

axiosrequiredpeer dependency: v1 required for interceptor functionality

Agent activity

49 hits · last 30 days

node

Resources

githubhttps://github.com/arthurfiorette/axios-cache-interceptor ↗

packageaxios-cache-interceptor ↗

homepagehttps://axios-cache-interceptor.js.org ↗