http-cookie-agent

http-cookie-agent bridges a gap in the Node.js HTTP ecosystem: most clients (global fetch, undici, node:http/https, node-fetch) have no built-in concept of a persistent cookie jar, forcing developers to manually read Set-Cookie headers and re-attach Cookie headers on every request. This package wraps a standard tough-cookie CookieJar around the request/response lifecycle of a wide range of clients, so cookies set by a server are automatically stored and replayed on subsequent requests to the same origin.

It ships dedicated HttpCookieAgent/HttpsCookieAgent/MixedCookieAgent classes for Node’s native http/https module (which axios, node-fetch, got, superagent, needle, and @hapi/wreck all build on), a createCookieAgent factory for wrapping any other Agent subclass such as agentkeepalive or http-proxy-agent, and both an Agent-style CookieAgent and a composable cookie() interceptor for undici’s dispatcher pipeline (with a separate /undici/v6 entry point for older undici majors). The library has no runtime dependency beyond agent-base and treats tough-cookie and undici as peer dependencies, keeping it lightweight and letting consumers control exact version pinning.

What You Get

• HttpCookieAgent / HttpsCookieAgent / MixedCookieAgent classes that drop in as replacements for Node’s http.Agent/https.Agent
• A createCookieAgent(BaseAgentClass) factory for adding cookie support to any third-party Agent subclass
• An undici CookieAgent dispatcher plus a composable cookie() interceptor for Dispatcher.compose() pipelines
• A /undici/v6 build for projects still on undici v6, alongside the default build targeting undici v7/v8
• Automatic Set-Cookie capture and Cookie header injection with no manual header plumbing required

Common Use Cases

• Session-authenticated scraping with axios or node-fetch, sharing one CookieJar across every request
• Testing cookie-based auth flows by replaying login cookies automatically across a test suite
• Migrating off the deprecated request/request-promise libraries while keeping their built-in cookie jar behavior
• Adding cookie persistence to internal service clients built on undici’s dispatcher/interceptor model

Under The Hood

Architecture The library is organized by target client family under src/http, src/undici, and src/undici/v6, all sharing common cookie logic in src/cookie_options.ts and src/utils/ (create_cookie_header_value.ts, save_cookies_from_header.ts, validate_cookie_options.ts). The http family works by monkey-patching a request’s _implicitHeader and emit methods inside createCookieAgent’s addRequest override: it injects a Cookie header just before headers are sent and intercepts the synthetic response event to persist Set-Cookie values into the jar, even re-writing already-buffered header chunks (kRecreateFirstChunk) when headers were sent before the override could apply. The undici family takes a cleaner, composition-based approach: CookieAgent composes a cookie() interceptor (createCookieInterceptor) that wraps each dispatch in a CookieHandler, so cookie logic runs entirely through undici’s own extension points with no private-API patching. This split reflects the two ecosystems’ different extensibility models, and changing either core abstraction (the http.Agent patching approach or the undici interceptor contract) would require reworking that family independently of the other.

Tech Stack Written in TypeScript, compiled with Babel (@babel/preset-typescript) rather than tsc, targeting Node.js 22+. Runtime dependencies are minimal — only agent-base — with tough-cookie (v4-v6) and undici (v7-v8, optional) declared as peer dependencies so consumers control exact versions. Devependencies cover the full client matrix it supports for testing: axios, got, node-fetch, superagent, needle, @hapi/wreck, urllib, agentkeepalive, and http-proxy-agent. Uses pnpm for package management, vitest for tests, eslint/prettier via a shared @3846masa/configs config, and release-it with conventional-changelog for automated releases.

Code Quality Tests live alongside source in __tests__ directories and are extensive — over 2000 lines across the http and undici suites alone, with dedicated spec files per supported client (axios, got, node-fetch, superagent, needle, wreck, agentkeepalive, http-proxy-agent) plus proxy and global-fetch scenarios. CI (GitHub Actions) runs lint and a test matrix across Node 22/24/26 on Ubuntu, macOS, and Windows. Type declarations are hand-augmented via declare module 'http' blocks to expose Node’s private _implicitHeader/_header/outputData internals with proper types rather than casting through any. Error handling is explicit: internal overrides catch failures and call req.destroy(err) rather than letting them propagate silently. Linting is enforced with zero warnings (--max-warnings 0) and a separate tsc --noEmit pass for both the main build and the published .d.ts files.

API Design The public surface is intentionally narrow: a handful of Agent subclasses plus one factory function and one interceptor, all taking a single { cookies: { jar } } option that maps directly onto a tough-cookie CookieJar. Getting started requires no boilerplate beyond constructing a jar and passing it to the chosen Agent class, and the README documents an explicit compatibility table across eleven client libraries so users can quickly confirm support before adopting it. Naming is consistent across client families (HttpCookieAgent/HttpsCookieAgent/MixedCookieAgent, CookieAgent, cookie()), and the library explicitly flags in its docs when a target client (got, superagent) already has native cookie support and this package may be unnecessary — an unusually honest piece of API guidance.