Registry / devops / cache-headers

cache-headers

JSON →
library1.1.1jsnpmunverified

Generate browser and CDN cache header values as Express middleware. Version 1.1.1 (latest, stable). Low-activity package (no recent updates). Supports route-level and app-level configuration with glob patterns. Key differentiator: provides sensible defaults for Cache-Control, Surrogate-Control, and Last-Modified headers with options like stale-while-revalidate and stale-if-error for advanced caching strategies. Requires core-js peer dependency. Not actively maintained.

devops
npm install cache-headers
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · CACHE-HEADERS
C
cache-headers
devopsjavascriptv1.1.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.

module.exports
✓ const cache = require('cache-headers');
✗ import cache from 'cache-headers'; // CJS package, not ESM
This package uses CommonJS (require). Default export is an object with setupInitialCacheHeaders and overrideCacheHeaders functions.
setupInitialCacheHeaders
✓ app.use(cache.setupInitialCacheHeaders(pathsConfig));
✗ app.use(cache.setupInitialCacheHeaders); // missing pathsConfig argument
Function must be called with a config object (pathsConfig). It returns middleware.
overrideCacheHeaders
✓ router.get('/path', cache.overrideCacheHeaders({ maxAge: 2000 }), handler);
✗ router.get('/path', cache.overrideCacheHeaders, handler); // missing config argument
Function must be called with a configuration object. It returns middleware to override previously set headers.

Shows app-level middleware setup with path-based cache configuration for Express.

const express = require('express'); const cache = require('cache-headers'); const app = express(); const pathsConfig = { paths: { '/**/images': { maxAge: 'ONE_DAY', staleRevalidate: 'ONE_HOUR' }, '/user/**': false, '/': 60 } }; app.use(cache.setupInitialCacheHeaders(pathsConfig)); app.get('/api/images/logo', (req, res) => { res.json({ url: 'logo.png' }); }); app.listen(3000);
Debug
Known issues
gotchaSetting maxAge to a number uses Surrogate-Control header, but Cache-Control default is no-cache, no-store, must-revalidate unless stale* options are used.
fix
Understand that Cache-Control and Surrogate-Control are set separately; maxAge only affects Surrogate-Control.
affects: >=1.0
deprecatedThe package requires core-js@^2.4.1 as a peer dependency, which is outdated. core-js v2 is no longer maintained.
fix
Consider using a newer caching middleware or update peer dependency to core-js v3 if compatible, or avoid using core-js polyfills globally.
affects: >=1.0
gotchaWhen setPrivate is true, maxAge is forced to 0 and Surrogate-Control max-age becomes 0, but Cache-Control already includes 'private' – this may not be obvious.
fix
Explicitly set maxAge to desired value but note that setting private forces maxAge=0. See documentation.
affects: >=1.0
gotchaThe paths config uses glob patterns (e.g., '/**/generic'), but only simple path matching is supported. Complex globs may not work as expected.
fix
Test glob patterns thoroughly or use simpler path structures.
affects: >=1.0
gotchaThe overrideCacheHeaders only overrides Surrogate-Control and Cache-Control, but not Last-Modified from the initial setup.
fix
If Last-Modified override is needed, handle it separately in route handler.
affects: >=1.0
Errors
Common errors & fixes
Cannot find module 'core-js'
core-js is a peer dependency and not automatically installed by npm/yarn.
fix
Run: npm install core-js@^2.4.1
TypeError: cache.setupInitialCacheHeaders is not a function
Importing incorrectly or package not installed properly.
fix
Ensure correct require: const cache = require('cache-headers'); and that the package is installed.
Surrogate-Control header not being set as expected
Misunderstanding that maxAge only affects Surrogate-Control, not Cache-Control.
fix
Check that maxAge is set correctly and that staleRevalidate/staleError are not overriding Cache-Control behavior.
Cache-Control: private, no-cache, no-store, must-revalidate
Passing false as value for a path triggers private mode with maxAge=0.
fix
If you want no caching, use false; if you want public caching, set a numeric maxAge or object with setPrivate: false.
Upgrade
Version history
1.1.1latest on npm
Audit
Dependencies
core-jsrequiredPeer dependency required for ES6+ polyfills (transpiled with Babel). Ensure version ^2.4.1 is installed.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/1stdibs/cache-headers ↗
packagecache-headers ↗
homepagehttps://github.com/1stdibs/cache-headers#readme ↗
cache-headers — npm install cache-headers · libregistry