fetch-cookie

fetch-cookie is a small TypeScript library that wraps a fetch function so it transparently manages cookies the way a browser would. It intercepts outgoing requests to attach the right Cookie header for the target URL, then reads Set-Cookie headers off the response and stores them in an internal cookie jar for future requests, all without any change to how you call fetch.

Because runtimes like Node.js historically shipped fetch without cookie-jar semantics, fetch-cookie fills that gap for server-side code, scripts, and testing tools that need session-aware HTTP calls — logging into a site, following an authenticated flow, or scraping a service that sets cookies on login. It works with the native global fetch, node-fetch, undici, and any spec-compliant fetch implementation, and it forwards cookies correctly across redirect chains, which most fetch polyfills do not handle on their own.

What You Get

• A drop-in wrapper: fetchCookie(fetch) returns a function with the exact same call signature as the fetch you passed in
• An internal tough-cookie CookieJar by default, or bring your own jar (including custom stores) as a second argument
• Direct access to the jar via fetchCookie.cookieJar to read or set cookies programmatically outside of a request
• Custom redirect handling (maxRedirect option) since the library takes over redirect: 'manual' internally to keep cookies flowing across redirects
• Automatic stripping of Authorization and Cookie headers when a redirect crosses to a different domain, matching browser security behavior
• Compatibility across the native global fetch, node-fetch v2/v3, and undici, verified by a CI test matrix

Common Use Cases

• Automating a login flow against a site or API that sets a session cookie, then reusing that session on subsequent requests
• Building CLI tools or scrapers that need to hold onto cookies across many sequential HTTP calls
• Writing integration tests against an app that relies on cookie-based sessions, without spinning up a real browser
• Talking to legacy or third-party HTTP APIs that use cookies rather than bearer tokens for authentication
• Running multiple isolated “sessions” concurrently by creating separate fetch-cookie instances, each with its own cookie jar

Under The Hood

Architecture The entire library lives in a single module (src/index.ts) structured as one higher-order function, fetchCookie(), that closes over a cookie jar and returns a wrapper matching the shape of the fetch function it was given. The wrapper reads the jar for a Cookie header before delegating to the underlying fetch, then writes any Set-Cookie response headers back into the jar; redirects are handled by forcing redirect: 'manual' on every call and recursively re-invoking the wrapper itself, so cookie application happens on every hop rather than being delegated to the underlying fetch implementation’s own redirect logic. This is a decorator pattern through and through: no global state, no class hierarchy, and the only external dependency for HTTP semantics is tough-cookie for jar storage and set-cookie-parser for splitting concatenated Set-Cookie header values.

Tech Stack Written in TypeScript, compiled to both ESM and CJS output via esbuild, with hand-written .d.ts declarations generated by tsc. Runtime dependencies are limited to tough-cookie (cookie jar and parsing) and set-cookie-parser (WhatWG-style header splitting). The package ships dual exports map entries for import/require consumers, targets Node’s native fetch as well as node-fetch and undici, and has no build-time framework beyond esbuild plus tsc for type declarations.

Code Quality Tests run under Mocha with Chai assertions against a small Express test server, exercising the library across node-fetch@2, node-fetch@3, and undici in one shared test suite to catch behavioral drift between fetch implementations. Linting is enforced with ts-standard, and tsc -noEmit gates type correctness in CI before tests run, with a GitHub Actions matrix covering multiple Node.js versions. Internal functions favor small, single-purpose helpers (isDomainOrSubdomain, identifyDeleteHeader, getCookiesFromResponse) with explicit handling for the differing header APIs across fetch implementations rather than a one-size-fits-all assumption.

What Makes It Unique Most fetch polyfills either ignore cookies entirely or only support them incidentally through whatever the underlying HTTP client does. fetch-cookie’s distinguishing choice is taking over redirect handling itself (redirect: 'manual' plus manual re-invocation) specifically so cookies set mid-redirect-chain are captured and forwarded correctly — including cross-origin security behavior like stripping Authorization/Cookie headers when a redirect changes domains, mirroring what browsers do natively. It also normalizes over multiple generations of Set-Cookie header shapes (node-fetch v1’s getAll, node-fetch v2’s raw(), and the WhatWG string form), letting one implementation work uniformly across the Node.js fetch ecosystem’s fragmented history.