{"id":17741,"library":"koa-cookie","title":"Koa Cookie Parser Middleware","description":"koa-cookie is a straightforward middleware for the Koa.js web framework, designed to parse HTTP `Cookie` headers and expose their contents as a convenient JavaScript object on `ctx.cookie`. Currently at version 1.0.0, this package provides a minimalist solution for accessing request cookies without additional features like cookie signing or complex serialization, adhering to a 'do one thing well' philosophy. Its release cadence is stable, with v1.0.0 being the primary and seemingly final release, indicating a maintenance-only status rather than active feature development. Key differentiators include its extreme simplicity and direct integration with Koa's context object, making it easy to drop into existing Koa applications, including those using `koa-router`. It's suitable for applications that handle cookie security (signing, encryption) at a different layer or don't require such features from the parser itself.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/varunpal/koa-cookie","tags":["javascript","koa","cookie","middleware","parser","cookie-parser","koa-router"],"install":[{"cmd":"npm install koa-cookie","lang":"bash","label":"npm"},{"cmd":"yarn add koa-cookie","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-cookie","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `koa-cookie` package exports its middleware function as the default export for ESM.","wrong":"import { cookie } from 'koa-cookie';","symbol":"cookie","correct":"import cookie from 'koa-cookie';"},{"note":"CommonJS `require` is demonstrated in the `koa-router` example, indicating support.","symbol":"cookie","correct":"const cookie = require('koa-cookie');"},{"note":"The middleware directly attaches the parsed cookie object to the `ctx` object, not `ctx.request`.","wrong":"const cookies = ctx.request.cookie;","symbol":"ctx.cookie","correct":"const cookies = ctx.cookie;"}],"quickstart":{"code":"import Koa from 'koa';\nimport cookie from 'koa-cookie';\n\nconst app = new Koa();\n\n// Apply the cookie middleware\napp.use(cookie());\n\n// A simple route to demonstrate cookie access\napp.use(async (ctx, next) => {\n  if (ctx.path === '/') {\n    const allCookies = ctx.cookie;\n    console.log('Received cookies:', allCookies);\n    \n    // Example: access a specific cookie\n    const userName = allCookies.name || 'Guest';\n    ctx.body = `Hello, ${userName}! Your raw cookies: ${JSON.stringify(allCookies)}`;\n  } else {\n    await next();\n  }\n});\n\n// Simulate setting a cookie (not part of koa-cookie itself)\napp.use(async (ctx, next) => {\n  if (ctx.path === '/set-cookie') {\n    ctx.cookies.set('name', 'John Doe', { httpOnly: true, maxAge: 3600000 });\n    ctx.cookies.set('session_id', 'abcd123xyz', { httpOnly: true, maxAge: 3600000 });\n    ctx.body = 'Cookies set!';\n  } else {\n    await next();\n  }\n});\n\nconst port = process.env.PORT || 3000;\napp.listen(port, () => console.log(`Server running on http://localhost:${port}`));","lang":"javascript","description":"This quickstart demonstrates how to initialize `koa-cookie` middleware and access parsed cookies via `ctx.cookie` in a simple Koa application, along with an example of setting cookies (which `koa-cookie` does not handle directly)."},"warnings":[{"fix":"Ensure `app.use(cookie());` is called at the top of your middleware stack, before router or business logic middleware.","message":"Middleware order is crucial. `koa-cookie` must be `app.use()`'d *before* any route handlers or other middleware that intend to access `ctx.cookie`, otherwise `ctx.cookie` will be undefined.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement cookie signing/encryption separately (e.g., with `koa-session`, `koa-csrf`, or by manually using cryptographic libraries) or choose a more feature-rich session management library if these features are required.","message":"This package is a basic cookie parser and does *not* provide cookie signing, encryption, or other security features. Cookies parsed by `koa-cookie` are raw string values. For secure applications, consider using `koa-session` or similar solutions that handle signing and other security aspects.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new projects or long-term stability, consider alternative, actively maintained cookie parsing or session management solutions for Koa. If using it, regularly test for compatibility and security issues.","message":"The `koa-cookie` package appears to be unmaintained, with its last update occurring over 5 years ago. While it provides basic functionality, it might not be compatible with future Koa versions or address potential security vulnerabilities found in newer Node.js or browser environments.","severity":"deprecated","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":"Make sure `app.use(cookie());` is called once at the start of your application's middleware chain.","cause":"The `koa-cookie` middleware was not applied or was applied after the code attempting to access `ctx.cookie`.","error":"TypeError: Cannot read properties of undefined (reading 'cookie')"},{"fix":"Verify that `app.use(cookie());` is one of the first middleware applied to your Koa application. Inspect incoming headers with a debugging tool to ensure the 'Cookie' header is present as expected.","cause":"This is likely due to the `koa-cookie` middleware being placed incorrectly in the middleware chain, or a preceding middleware consuming/modifying the `Cookie` header before `koa-cookie` can process it.","error":"Cookies are not being parsed/found in ctx.cookie, even though they are present in the 'Cookie' header."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}