{"id":16063,"library":"http-cookie-agent","title":"HTTP Cookie Agent","description":"http-cookie-agent is a Node.js library that provides HTTP(S) agents capable of managing cookies across various popular HTTP clients, including Node.js global fetch (via undici), undici directly, axios, node-fetch, and the native `node:http`/`node:https` modules. Its current stable version is 7.0.3, with minor bug fix releases occurring relatively frequently and major versions released annually or as significant changes warrant. The library primarily differentiates itself by offering a unified cookie management solution that integrates seamlessly with existing `tough-cookie` instances and supports a wide array of HTTP client libraries, allowing developers to centralize cookie handling in complex Node.js applications without reimplementing logic for each client. It requires `tough-cookie` and, for `fetch` integration, `undici` as peer dependencies.","status":"active","version":"7.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/3846masa/http-cookie-agent","tags":["javascript","agent","axios","cookies","fetch","got","http","https","needle"],"install":[{"cmd":"npm install http-cookie-agent","lang":"bash","label":"npm"},{"cmd":"yarn add http-cookie-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-cookie-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for robust cookie parsing, storage, and management. It provides the `CookieJar` implementation.","package":"tough-cookie","optional":false},{"reason":"Required when using `http-cookie-agent` with Node.js global fetch or directly with the `undici` client. Specific versions of `undici` are tied to Node.js versions.","package":"undici","optional":true}],"imports":[{"note":"CookieJar is the core cookie management class from the `tough-cookie` peer dependency.","wrong":"const { CookieJar } = require('tough-cookie');","symbol":"CookieJar","correct":"import { CookieJar } from 'tough-cookie';"},{"note":"The primary agent for `undici` based clients (including Node.js global fetch). Be mindful of specific `undici` versions, e.g., `/undici/v6` for older Node.js versions.","wrong":"const { CookieAgent } = require('http-cookie-agent/undici');\nimport { CookieAgent } from 'http-cookie-agent';","symbol":"CookieAgent","correct":"import { CookieAgent } from 'http-cookie-agent/undici';"},{"note":"Use `HttpsCookieAgent` or `HttpCookieAgent` from `http-cookie-agent/http` for native `node:https` and `node:http` modules, respectively.","wrong":"import { CookieAgent } from 'http-cookie-agent/http';","symbol":"HttpsCookieAgent","correct":"import { HttpsCookieAgent } from 'http-cookie-agent/http';"},{"note":"This named export provides an `undici` interceptor function, which is an alternative to using `CookieAgent` directly for `undici`'s `Agent` composition pattern.","wrong":"import { CookieAgent } from 'http-cookie-agent/undici';","symbol":"cookie (undici interceptor)","correct":"import { cookie } from 'http-cookie-agent/undici';"}],"quickstart":{"code":"import { CookieJar } from 'tough-cookie';\nimport { CookieAgent } from 'http-cookie-agent/undici';\nimport { fetch } from 'undici'; // Or use global fetch if undici is installed for Node.js >=20\n\nasync function makeRequestWithCookies() {\n  const jar = new CookieJar();\n  const agent = new CookieAgent({ cookies: { jar } });\n\n  console.log('Sending first request to set a cookie...');\n  const firstResponse = await fetch('https://httpbin.org/cookies/set?mycookie=myvalue', {\n    dispatcher: agent\n  });\n  console.log(`First request status: ${firstResponse.status}`);\n  await firstResponse.text(); // Consume body to ensure cookies are processed\n\n  console.log('Sending second request to retrieve the cookie...');\n  const secondResponse = await fetch('https://httpbin.org/cookies', {\n    dispatcher: agent\n  });\n  console.log(`Second request status: ${secondResponse.status}`);\n  const cookieData = await secondResponse.json();\n  console.log('Cookies received in second request:', cookieData.cookies);\n\n  if (cookieData.cookies.mycookie === 'myvalue') {\n    console.log('Success: Cookie was correctly sent and received!');\n  } else {\n    console.log('Failure: Cookie was not handled as expected.');\n  }\n}\n\nmakeRequestWithCookies().catch(console.error);","lang":"typescript","description":"Demonstrates how to initialize `CookieJar` and `CookieAgent` for `undici` (or Node.js global `fetch`), making two requests to `httpbin.org` to set and then retrieve a cookie."},"warnings":[{"fix":"Refer to the `MIGRATION.md` guide on the `http-cookie-agent` GitHub repository to understand the necessary code adjustments for v7.x.","message":"Version 7.0.0 introduced breaking changes. Users upgrading from v6 should consult the `MIGRATION.md` file in the GitHub repository for detailed instructions.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure `tough-cookie` is installed (`npm install tough-cookie`). For `fetch` or `undici` usage, also install `undici` (`npm install undici`). Check the `http-cookie-agent` README for recommended `undici` versions based on your Node.js version.","message":"This package has peer dependencies (`tough-cookie` and `undici`) that must be installed separately. Failing to install them will result in runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"This library is designed for Node.js environments. For Bun or Deno, consider their native cookie handling capabilities or alternative libraries designed for those runtimes.","message":"`http-cookie-agent` explicitly does not support Bun's and Deno's proprietary `fetch` implementations due to their differing internal structures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Remove the `async_UNSTABLE` option from your `CookieAgent` configuration. Review alternative asynchronous cookie handling strategies if this feature was critical to your use case.","message":"The `async_UNSTABLE` option was removed in version 6.0.4 due to incorrect functionality. Code relying on this option will no longer work.","severity":"breaking","affected_versions":">=6.0.4"},{"fix":"Install the correct `undici` version matching your Node.js environment as specified in the `http-cookie-agent` documentation (e.g., `npm install undici@7`).","message":"Node.js global `fetch` support relies on `undici`. The required `undici` version might vary depending on your Node.js version (e.g., `undici@6` for Node.js 20/22/23, `undici@7` for Node.js 24).","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Upgrade your Node.js environment to version 20.0.0 or newer. If you need to support older Node.js versions, consider using an older major version of `http-cookie-agent` that supports your target Node.js runtime, if available.","message":"This library requires Node.js version 20.0.0 or higher. Running on older Node.js versions will lead to compatibility issues or errors.","severity":"gotcha","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install tough-cookie` in your project directory.","cause":"The `tough-cookie` peer dependency is not installed.","error":"Error: Cannot find package 'tough-cookie' imported from ..."},{"fix":"Run `npm install undici` and ensure you are on a compatible Node.js version (>=20.0.0). If you're on Node.js 20+, `fetch` should be global once `undici` is installed, or you can `import { fetch } from 'undici';`.","cause":"This usually indicates that `undici` is not installed, or the Node.js version being used does not natively provide global `fetch` without `undici`.","error":"TypeError: fetch is not a function"},{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import` statements. Verify the correct import path, such as `import { CookieAgent } from 'http-cookie-agent/undici';`.","cause":"Attempting to `require` the `CookieAgent` or other ESM-only exports in a CommonJS context, or using an incorrect import path.","error":"TypeError: CookieAgent is not a constructor"},{"fix":"Ensure you are passing an instance of `CookieAgent` to the `dispatcher` option, e.g., `new CookieAgent({ cookies: { jar } })`. Do not pass the class itself or an uninitialized object.","cause":"When using `undici` or Node.js global fetch, the `dispatcher` option expects an instance of an `undici` dispatcher. This error often arises if `CookieAgent` is not correctly instantiated or passed.","error":"Error: `dispatcher` must be an instance of `Dispatcher`."}],"ecosystem":"npm"}