{"id":17141,"library":"popsicle-cookie-jar","title":"Popsicle Cookie Jar Middleware","description":"popsicle-cookie-jar is a middleware designed for the Popsicle HTTP client library, enabling cookie management in Node.js environments. It integrates with Popsicle's request lifecycle to automatically handle `Set-Cookie` headers from responses and attach `Cookie` headers to outgoing requests, mimicking browser-like cookie behavior. The current stable version is 1.0.1, which primarily features an update to the underlying `tough-cookie` library for security patches. Given its single-purpose nature and recent release history, its release cadence appears to be driven by bug fixes or critical dependency updates rather than frequent feature additions. Key differentiators include its tight integration with the Popsicle ecosystem and its reliance on `tough-cookie` for robust cookie specification adherence, providing a reliable, in-memory cookie store by default, with options for custom `CookieJar` instances.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/serviejs/popsicle-cookie-jar","tags":["javascript","popsicle","cookies","jar","memory","store","typescript"],"install":[{"cmd":"npm install popsicle-cookie-jar","lang":"bash","label":"npm"},{"cmd":"yarn add popsicle-cookie-jar","lang":"bash","label":"yarn"},{"cmd":"pnpm add popsicle-cookie-jar","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the core `servie` request/response interface that Popsicle builds upon.","package":"servie","optional":false}],"imports":[{"note":"The library primarily uses named exports. While CommonJS `require` works, the recommended approach in modern Node.js is ESM `import`.","wrong":"const cookies = require('popsicle-cookie-jar').cookies;","symbol":"cookies","correct":"import { cookies } from 'popsicle-cookie-jar';"},{"note":"Used for explicitly providing a custom `tough-cookie` compatible `CookieJar` instance to the middleware.","wrong":"const { CookieJar } = require('popsicle-cookie-jar');","symbol":"CookieJar","correct":"import { CookieJar } from 'popsicle-cookie-jar';"},{"note":"While used in examples for `popsicle-cookie-jar`, `compose` is a utility typically provided by `servie` itself or a similar middleware orchestration library, not directly from this package. Make sure to import it from the correct source, usually `servie`.","wrong":"import { compose } from 'popsicle-cookie-jar';","symbol":"compose","correct":"import { compose } from 'servie';"}],"quickstart":{"code":"import { cookies, CookieJar } from \"popsicle-cookie-jar\";\nimport { compose } from 'servie';\n// Assume 'transport' is another middleware, e.g., from 'popsicle-transport-http'\n// For demonstration, we'll create a dummy transport and Popsicle client.\n\ninterface Context {\n  request: { url: string; headers?: Record<string, string>; };\n  response?: { status: number; headers: Record<string, string>; body?: any; };\n}\n\nasync function dummyTransport(ctx: Context, next: () => Promise<void>) {\n  console.log(`Sending request to: ${ctx.request.url}`);\n  ctx.response = {\n    status: 200,\n    headers: { 'Set-Cookie': 'session=abc; Path=/; HttpOnly' },\n    body: 'Hello World'\n  };\n  await next();\n}\n\n// Create an in-memory cookie jar\nconst myCookieJar = new CookieJar();\n\n// Compose the middleware with a custom cookie jar\nconst middlewareWithJar = compose([cookies(myCookieJar), dummyTransport]);\n\n// Or let it create a default in-memory jar\nconst middlewareDefault = compose([cookies(), dummyTransport]);\n\nasync function makeRequest(middleware: (ctx: Context, next: () => Promise<void>) => Promise<void>) {\n  const ctx: Context = { request: { url: 'http://example.com/login' } };\n  await middleware(ctx, async () => {}); // No further middleware after transport\n  console.log('Response headers:', ctx.response?.headers);\n  console.log('Cookies in jar (after request):', myCookieJar.getCookiesSync('http://example.com/login'));\n}\n\nconsole.log('--- Using custom CookieJar ---');\nawait makeRequest(middlewareWithJar);\n\nconsole.log('\\n--- Using default (new) CookieJar instance for separate calls ---');\n// Each call to cookies() without an argument creates a new jar\nawait makeRequest(compose([cookies(), dummyTransport]));\n","lang":"typescript","description":"This quickstart demonstrates how to apply `popsicle-cookie-jar` middleware to a Popsicle client to enable automatic cookie handling, showing both default in-memory and custom `CookieJar` usage."},"warnings":[{"fix":"Initialize a `new CookieJar()` once and pass that same instance to `cookies()` for all related middleware compositions: `const myJar = new CookieJar(); const mw = compose([cookies(myJar), transport()]);`","message":"When using `cookies()` without an argument, an *in-memory* `CookieJar` is created. If you create multiple middleware instances this way (e.g., for different requests or clients), they will each have their own independent cookie stores, which might not be the desired behavior for persistent sessions. To share cookies, pass the same `CookieJar` instance.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install `popsicle-cookie-jar` (`npm install popsicle-cookie-jar`) and include `cookies()` in your middleware chain: `compose([cookies(), transport()])`.","message":"The `popsicle` library (which this middleware extends) moved its core cookie functionality into `popsicle-cookie-jar` starting from `popsicle` v10.0.0. If you are upgrading `popsicle` from an older version, you must now explicitly install and include `popsicle-cookie-jar` middleware to retain cookie support.","severity":"breaking","affected_versions":">=10.0.0 of popsicle"},{"fix":"Regularly update `popsicle-cookie-jar` to ensure you benefit from `tough-cookie` security patches. Consult the `tough-cookie` documentation for advanced cookie management needs or debugging.","message":"While `popsicle-cookie-jar` provides cookie functionality, it relies on `tough-cookie` for the actual cookie parsing and storage logic. Developers should be aware of `tough-cookie`'s API and limitations, especially concerning cookie domain matching and path rules, as well as any security advisories related to `tough-cookie` itself.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate newer, actively maintained HTTP clients and their cookie management solutions if starting a new project or if long-term feature support is a concern.","message":"As this package is middleware for `popsicle`, users should be aware that `popsicle` itself appears to be in a maintenance-only state with no recent feature development, suggesting this middleware will likely follow a similar pattern. Consider alternatives if active development and a robust feature roadmap are critical.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `servie`: `npm install servie`.","cause":"The `servie` package is a peer dependency but has not been installed.","error":"Error: Cannot find module 'servie'"},{"fix":"Ensure `popsicle-cookie-jar` is used within a valid Popsicle/Servie middleware chain where the `context.request` object is properly initialized before `cookies()` is called.","cause":"The `popsicle-cookie-jar` middleware expects the `context.request` object to exist, typically populated by a preceding middleware or the initial Popsicle client call.","error":"TypeError: Cannot read properties of undefined (reading 'headers') at cookiesMiddleware"}],"ecosystem":"npm","meta_description":null}