{"id":17738,"library":"koa-cache-control","title":"Koa Cache Control Middleware","description":"The `koa-cache-control` package provides Koa middleware for declarative management of HTTP `Cache-Control` headers. Currently stable at version 2.0.0, it offers a simple API to configure caching behaviors, including `no-cache`, `max-age`, `public`, `private`, and `no-store`. The package helps consolidate common caching patterns, such as automatically setting `max-age=0` when `no-cache` is enabled. While its release cadence has been relatively slow, with its last major update aligning with Koa 2.x, it specifically targets Koa applications, providing a more integrated approach than manually manipulating headers directly. It supports both Koa 1.x (generator-based) and Koa 2.x (async/await based) applications.","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/DaMouse404/koa-cache-control","tags":["javascript","Koa","cache","cache-control","no-cache"],"install":[{"cmd":"npm install koa-cache-control","lang":"bash","label":"npm"},{"cmd":"yarn add koa-cache-control","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-cache-control","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The middleware factory is exported as a default export.","wrong":"import { cacheControl } from 'koa-cache-control';","symbol":"cacheControl","correct":"import cacheControl from 'koa-cache-control';"},{"note":"For CommonJS environments, the middleware factory is the module's default export.","symbol":"cacheControl (CJS)","correct":"const cacheControl = require('koa-cache-control');"},{"note":"After the middleware is loaded, cache control options can be overridden directly on `ctx.cacheControl` (or `this.cacheControl` in Koa 1.x generators).","symbol":"Context property","correct":"ctx.cacheControl = { maxAge: 60 };"}],"quickstart":{"code":"import Koa from 'koa';\nimport cacheControl from 'koa-cache-control';\n\nconst app = new Koa();\n\n// Apply middleware with default maxAge of 5 seconds\napp.use(cacheControl({\n    maxAge: 5\n}));\n\n// Example route where cache control is set dynamically\napp.use(async (ctx, next) => {\n    if (ctx.path === '/no-cache-page') {\n        ctx.cacheControl = {\n            noCache: true\n        };\n        ctx.body = 'This page will not be cached.';\n    } else if (ctx.path === '/long-cache-page') {\n        ctx.cacheControl = {\n            maxAge: 3600, // 1 hour\n            public: true\n        };\n        ctx.body = 'This page is cached for 1 hour.';\n    } else {\n        ctx.body = 'Default cached page (5 seconds).';\n    }\n    await next();\n});\n\napp.listen(3000, () => {\n    console.log('Koa server running on http://localhost:3000');\n    console.log('Try http://localhost:3000/ and http://localhost:3000/no-cache-page');\n});","lang":"typescript","description":"Sets up a basic Koa application using `koa-cache-control` with default settings and demonstrates dynamic override on specific routes."},"warnings":[{"fix":"Rewrite generator functions to async/await syntax: `app.use(async (ctx, next) => { /* ... */ await next(); });`","message":"While v2.0.0 explicitly supports Koa 2.x (async/await), many older examples and documentation excerpts may still show Koa 1.x generator function syntax (e.g., `function *(next){ yield next; }`). Ensure your application's middleware functions are updated to `async (ctx, next) => { await next(); }` for Koa 2.x compatibility.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Be aware of option interactions. If `no-cache` is desired but with a specific `max-age` or other directives, manually construct the header or ensure `noCache` is not set.","message":"Setting the `noCache` option will automatically apply `max-age=0` and remove `sMaxAge`, `staleIfError`, and `staleWhileRevalidate` from the generated `Cache-Control` header. This implicit behavior might override other caching directives you intended.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always set `ctx.cacheControl` at the beginning of your route handler or before calling `await next()` if you need to modify caching behavior based on subsequent logic.","message":"The package uses `ctx.cacheControl` (or `this.cacheControl` in Koa 1.x) to allow overriding default options within specific routes. Ensure you set this property *before* `ctx.body` is set or the response is sent, as headers are typically finalized early in the response lifecycle.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure you have `import Koa from 'koa'; const app = new Koa();` and that `app` is correctly instantiated before using `.use()`.","cause":"Attempting to use Koa middleware with a non-Koa application instance or an incorrectly initialized Koa app.","error":"TypeError: app.use is not a function"},{"fix":"Verify `app.use(cacheControl(...))` is called early in your middleware chain. Check for other middleware or manual `ctx.set('Cache-Control', ...)` calls that might conflict. Inspect the generated header using browser developer tools or `curl -v`.","cause":"Middleware is not applied or is being overridden by other middleware/manual header settings, or options are conflicting (e.g., `noCache` overriding `maxAge`).","error":"Cache-Control header not appearing or having unexpected values"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}