Registry / http-networking / http-cookie-agent

http-cookie-agent

library7.0.3jsnpmunverified

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.

http-networking serialization

npm install http-cookie-agent

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-COOKIE-AGENT

http-cookie-agent

http-networkingjavascriptv7.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CookieJar

✓ import { CookieJar } from 'tough-cookie';

✗ const { CookieJar } = require('tough-cookie');

CookieJar is the core cookie management class from the `tough-cookie` peer dependency.

CookieAgent

✓ import { CookieAgent } from 'http-cookie-agent/undici';

✗ const { CookieAgent } = require('http-cookie-agent/undici'); import { CookieAgent } from 'http-cookie-agent';

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.

HttpsCookieAgent

✓ import { HttpsCookieAgent } from 'http-cookie-agent/http';

✗ import { CookieAgent } from 'http-cookie-agent/http';

Use `HttpsCookieAgent` or `HttpCookieAgent` from `http-cookie-agent/http` for native `node:https` and `node:http` modules, respectively.

cookie (undici interceptor)

✓ import { cookie } from 'http-cookie-agent/undici';

✗ import { CookieAgent } from 'http-cookie-agent/undici';

This named export provides an `undici` interceptor function, which is an alternative to using `CookieAgent` directly for `undici`'s `Agent` composition pattern.

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.

import { CookieJar } from 'tough-cookie'; import { CookieAgent } from 'http-cookie-agent/undici'; import { fetch } from 'undici'; // Or use global fetch if undici is installed for Node.js >=20 async function makeRequestWithCookies() { const jar = new CookieJar(); const agent = new CookieAgent({ cookies: { jar } }); console.log('Sending first request to set a cookie...'); const firstResponse = await fetch('https://httpbin.org/cookies/set?mycookie=myvalue', { dispatcher: agent }); console.log(`First request status: ${firstResponse.status}`); await firstResponse.text(); // Consume body to ensure cookies are processed console.log('Sending second request to retrieve the cookie...'); const secondResponse = await fetch('https://httpbin.org/cookies', { dispatcher: agent }); console.log(`Second request status: ${secondResponse.status}`); const cookieData = await secondResponse.json(); console.log('Cookies received in second request:', cookieData.cookies); if (cookieData.cookies.mycookie === 'myvalue') { console.log('Success: Cookie was correctly sent and received!'); } else { console.log('Failure: Cookie was not handled as expected.'); } } makeRequestWithCookies().catch(console.error);

Debug

Known issues

breakingVersion 7.0.0 introduced breaking changes. Users upgrading from v6 should consult the `MIGRATION.md` file in the GitHub repository for detailed instructions.

fix

Refer to the `MIGRATION.md` guide on the `http-cookie-agent` GitHub repository to understand the necessary code adjustments for v7.x.

affects: >=7.0.0

gotchaThis package has peer dependencies (`tough-cookie` and `undici`) that must be installed separately. Failing to install them will result in runtime errors.

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.

affects: >=1.0.0

gotcha`http-cookie-agent` explicitly does not support Bun's and Deno's proprietary `fetch` implementations due to their differing internal structures.

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.

affects: >=1.0.0

breakingThe `async_UNSTABLE` option was removed in version 6.0.4 due to incorrect functionality. Code relying on this option will no longer work.

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.

affects: >=6.0.4

gotchaNode.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).

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`).

affects: >=6.0.0

gotchaThis library requires Node.js version 20.0.0 or higher. Running on older Node.js versions will lead to compatibility issues or errors.

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.

affects: >=7.0.0

Errors

Common errors & fixes

Error: Cannot find package 'tough-cookie' imported from ...

The `tough-cookie` peer dependency is not installed.

fix

Run `npm install tough-cookie` in your project directory.

TypeError: fetch is not a function

This usually indicates that `undici` is not installed, or the Node.js version being used does not natively provide global `fetch` without `undici`.

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';`.

TypeError: CookieAgent is not a constructor

Attempting to `require` the `CookieAgent` or other ESM-only exports in a CommonJS context, or using an incorrect import path.

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';`.

Error: `dispatcher` must be an instance of `Dispatcher`.

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.

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.

Upgrade

Version history

7.0.3latest on npm

Audit

Dependencies

tough-cookierequiredRequired for robust cookie parsing, storage, and management. It provides the `CookieJar` implementation.

undicioptionalRequired 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.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/3846masa/http-cookie-agent ↗

packagehttps://www.npmjs.com/package/http-cookie-agent ↗