Registry / web-framework / apicache

apicache

JSON →
library0.1.1jsnpmunverified

apicache is an ultra-simplified middleware for Express.js and Node.js designed to cache API responses. It supports both an in-memory store and Redis as a backend, allowing developers to define cache durations using plain-english strings (e.g., '5 minutes'). The current stable version is 1.6.3, with version 1.0.0 marking a production-ready release after extensive use. The project appears to have a moderate release cadence, focusing on stability and adding features incrementally, such as `res.write` support and official `compression` integration. Its key differentiator is its ease of use and 'automagic' caching injection into routes, making it a straightforward choice for basic API caching needs compared to more complex caching solutions.

npm install apicache
INSTALL
IMPORT
SIG · APICACHE
A
apicache
web-frameworkjavascriptv0.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

apicache
import apicache from 'apicache'
const apicache = require('apicache').apicache
The default export is the main `apicache` object, which contains `middleware`, `options`, `getPerformance`, etc.
middleware
import apicache from 'apicache'; let cache = apicache.middleware;
import { middleware } from 'apicache'
`middleware` is a property of the default `apicache` object, not a named export. Ensure you import the default first.
options
import apicache from 'apicache'; apicache.options({ ... })
import { options } from 'apicache'
`options` is a method of the default `apicache` object, used for global configuration, not a named export.
clear
import apicache from 'apicache'; apicache.clear('target')
import { clear } from 'apicache'
`clear` is a method of the default `apicache` object for manually invalidating cache entries or groups.

This example sets up an Express server with `apicache` configured for either in-memory or Redis caching. It demonstrates how to apply caching middleware to a route, retrieve cache performance metrics, view the cache index, and manually clear cached entries by target or group.

import express from 'express'; import apicache from 'apicache'; import redis from 'redis'; // Optional: for Redis integration const app = express(); // --- Configuration for in-memory cache --- let cache = apicache.middleware; // --- Configuration for Redis cache (uncomment to use) --- // const redisClient = redis.createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:6379' }); // redisClient.on('error', (err) => console.error('Redis Client Error', err)); // redisClient.connect(); // Connect the client // let cache = apicache.options({ redisClient }).middleware; // Basic cached route (in-memory or Redis based on config above) app.get('/api/data', cache('1 minute'), (req, res) => { console.log('Fetching fresh data for /api/data'); res.json({ timestamp: new Date(), value: Math.random() }); }); // Route to check cache performance and index app.get('/api/cache/performance', (req, res) => { res.json(apicache.getPerformance()); }); app.get('/api/cache/index', (req, res) => { res.json(apicache.getIndex()); }); // Route to manually clear cache (e.g., all entries, or a specific target/group) app.get('/api/cache/clear/:target?', (req, res) => { const target = req.params.target || 'all'; // 'all' clears everything if no target is specified console.log(`Clearing cache for target: ${target}`); res.json(apicache.clear(target)); }); const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); console.log('Try visiting http://localhost:3000/api/data multiple times quickly.'); console.log('Then try http://localhost:3000/api/cache/clear'); });
Debug
Known issues
gotchaWhen using `apicache` with the `compression` middleware, ensure `compression` is applied *before* `apicache` in the middleware chain for `apicache` to cache the compressed response. Older versions might have had issues with header mutation, but v0.8.0 and later addressed this.
fix
Ensure `app.use(compression());` comes before `app.use(apicache.middleware('duration'));` or before any route-specific cache middleware.
affects: <0.8.0
breakingThe injection of `apicache-store` and `apicache-version` headers moved from before cache-injection to response-building from cache. This means middleware interceptors will only detect these headers when a response is actually served from the cache, not when the request is initially processed.
fix
Adjust any custom middleware that relies on `apicache` headers to check for their presence during the response phase, specifically when a cache hit occurs.
affects: >=0.7.1
gotchaDebugging output for apicache, while configurable via `apicache.options({ debug: true })`, is now primarily and preferentially controlled via the `DEBUG` environment variable, specifically `DEBUG=apicache`.
fix
For detailed logging, set the environment variable `export DEBUG=apicache` before running your Node.js application instead of relying solely on `options({ debug: true })`.
affects: >=0.2.0
breakingapicache requires Node.js version 8 or higher. Using it with older Node.js versions will lead to compatibility issues or failures.
fix
Upgrade your Node.js environment to version 8 or newer.
affects: <8.0.0
gotchaWhen using `apicache.options()` to configure global settings (like `redisClient` or custom `headers`), ensure you apply it before initializing your `apicache.middleware`. Calling `options` modifies the global `apicache` object.
fix
Set global options before creating or using the `middleware` instance: `let cache = apicache.options({ /* ... */ }).middleware;`
affects: >=0.0.1
Errors
Common errors & fixes
TypeError: apicache.middleware is not a function
Incorrect import pattern, attempting to destructure `middleware` from `apicache` directly, or not importing `apicache` at all.
fix
Ensure you are importing the default `apicache` object: `import apicache from 'apicache';` and then accessing `middleware` as a property: `let cache = apicache.middleware;`
Error: Redis connection to localhost:6379 failed - connect ECONNREFUSED
The Redis server is not running or is not accessible at the specified host and port.
fix
Start your Redis server, verify its configuration (host/port), and ensure your application has network access to it. If using a custom URL, ensure `redis.createClient({ url: '...' })` is correct.
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax in an ES Module (`.mjs` file or `type: "module"` in `package.json`) environment.
fix
Replace `const apicache = require('apicache');` with `import apicache from 'apicache';`
Cache is not clearing/invalidating as expected.
Incorrect `apicache.clear()` target, or misunderstanding of cache grouping.
fix
Verify the target string passed to `apicache.clear(target)` matches an exact URL path or a `req.apicacheGroup` name. Use `apicache.getIndex()` to inspect current cached entries and groups to ensure correct targeting.
Upgrade
Version history
0.1.1latest on npm
Audit
Dependencies
redisoptionalOptional dependency for using Redis as the cache store instead of the default in-memory store.
compressionoptionalOptional dependency for caching gzip-compressed responses; apicache provides official support for it.
Agent activity
24 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources