# http-cookie-agent

> Allows cookies with every Node.js HTTP clients.

Latest version **8.0.0** (published 2026-05-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install http-cookie-agent
pnpm add http-cookie-agent
yarn add http-cookie-agent
bun add http-cookie-agent
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 8.0.0 |
| Published | 2026-05-06 |
| First published | 2021-09-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 |
| Dependencies | 1 |
| Unpacked size | 35.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 53 |
| Author | 3846masa |
| Maintainers | 3846masa |
| Keywords | agent, axios, cookies, fetch, got, http, https, needle, node-fetch, phin, request, superagent, tough-cookie, urllib, undici |

## Links

- npm: https://www.npmjs.com/package/http-cookie-agent
- Repository: https://github.com/3846masa/http-cookie-agent
- Homepage: https://github.com/3846masa/http-cookie-agent#readme
- Issues: https://github.com/3846masa/http-cookie-agent/issues
- Funding: https://github.com/sponsors/3846masa
- npm.io page: https://npm.io/package/http-cookie-agent

## Dependencies (1)

- [agent-base](https://npm.io/package/agent-base.md) ^9.0.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 8.0.0 (latest) — 2026-05-06
- 7.0.4 — 2026-05-06
- 7.0.3 — 2025-11-15
- 7.0.2 — 2025-07-13
- 7.0.1 — 2025-04-13
- 7.0.0 — 2025-04-13
- 6.0.8 — 2024-12-12
- 6.0.7 — 2024-12-10
- 6.0.6 — 2024-09-23
- 6.0.5 — 2024-05-02
- 6.0.4 — 2024-05-02
- 6.0.3 — 2024-04-04
- 6.0.2 — 2024-04-02
- 6.0.1 — 2024-01-11
- 6.0.0 — 2024-01-11
- … 20 more at https://npm.io/package/http-cookie-agent/versions

## README

# HTTP Cookie Agent

![HTTP Cookie Agent](./docs/assets/ogp.jpg)

[![github sponsors](https://flat.badgen.net/badge/GitHub%20Sponsors/Support%20me%20%E2%9D%A4/ff69b4?icon=github)](https://github.com/sponsors/3846masa)
[![npm](https://flat.badgen.net/npm/v/http-cookie-agent)](https://www.npmjs.com/package/http-cookie-agent)
[![license](https://flat.badgen.net/badge/license/MIT/blue)](LICENSE)
[![standard-readme compliant](https://flat.badgen.net/badge/readme%20style/standard/green)](https://github.com/RichardLitt/standard-readme)

Allows cookies with every Node.js HTTP clients (e.g. Node.js global fetch, undici, axios, node-fetch).

## Table of Contents

- [Install](#install)
- [Usage](#usage)
  - [Supported libraries](#supported-libraries)
  - [Using with another Agent library](#using-with-another-agent-library)
- [Contributing](#contributing)
- [License](#license)

## Install

```bash
npm install http-cookie-agent tough-cookie
```

## Usage

See also [examples](./examples) for more details.

### Supported libraries

| Library              | Supported?        |
| -------------------- | ----------------- |
| Node.js global fetch | ✅                |
| `undici`             | ✅                |
| `node:http`          | ✅                |
| `node:https`         | ✅                |
| `axios`              | ✅                |
| `node-fetch`         | ✅                |
| `got`                | ✅ <sup>\*1</sup> |
| `superagent`         | ✅ <sup>\*1</sup> |
| `request`            | ✅ <sup>\*1</sup> |
| `needle`             | ✅                |
| `phin`               | ✅                |
| `@hapi/wrech`        | ✅                |
| `urllib`             | ✅                |
| Bun global fetch     | ❌ <sup>\*2</sup> |
| Deno global fetch    | ❌ <sup>\*2</sup> |

\*1: This library supports cookies by default. You may not need `http-cookie-agent`.

\*2: There have proprietary fetch implementation and is [not currently supported](https://github.com/3846masa/http-cookie-agent/issues/692).

#### Node.js global fetch

When you want to use Node.js global fetch, you should install `undici` additionally.

| Node.js version | undici version         |
| --------------- | ---------------------- |
| v26             | `npm install undici@8` |
| v24             | `npm install undici@7` |
| v22             | `npm install undici@6` |

```js
import { CookieJar } from 'tough-cookie';
import { CookieAgent } from 'http-cookie-agent/undici/v6';

const jar = new CookieJar();
const agent = new CookieAgent({ cookies: { jar } });

await fetch('https://example.com', { dispatcher: agent });
```

#### `undici`

```js
import { fetch } from 'undici';
import { CookieJar } from 'tough-cookie';
import { CookieAgent } from 'http-cookie-agent/undici';

const jar = new CookieJar();
const agent = new CookieAgent({ cookies: { jar } });

await fetch('https://example.com', { dispatcher: agent });
```

Alternatively, `http-cookie-agent` can be used as [interceptors](https://github.com/nodejs/undici/blob/v7.0.0/docs/docs/api/Dispatcher.md#dispatchercomposeinterceptors-interceptor).
In this case, the `cookie()` must be placed at the beginning of the interceptors.

```js
import { fetch, interceptors } from 'undici';
import { CookieJar } from 'tough-cookie';
import { cookie } from 'http-cookie-agent/undici';

const jar = new CookieJar();
const agent = new Agent()
  .compose(cookie({ jar }))
  .compose(interceptors.retry())
  .compose(interceptors.redirect({ maxRedirections: 3 }));

await fetch('https://example.com', { dispatcher: agent });
```

#### `node:http` / `node:https`

```js
import https from 'node:https';

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

const jar = new CookieJar();
const agent = new HttpsCookieAgent({ cookies: { jar } });

https.get('https://example.com', { agent }, (res) => {
  // ...
});
```

#### `axios`

```js
import axios from 'axios';
import { CookieJar } from 'tough-cookie';
import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

const client = axios.create({
  httpAgent: new HttpCookieAgent({ cookies: { jar } }),
  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
});

await client.get('https://example.com');
```

#### `node-fetch`

```js
import fetch from 'node-fetch';
import { CookieJar } from 'tough-cookie';
import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

const httpAgent = new HttpCookieAgent({ cookies: { jar } });
const httpsAgent = new HttpsCookieAgent({ cookies: { jar } });

await fetch('https://example.com', {
  agent: ({ protocol }) => {
    return protocol === 'https:' ? httpsAgent : httpAgent;
  },
});
```

#### `got`

:warning: `got` supports cookies by default. You may not need `http-cookie-agent`.

See https://github.com/sindresorhus/got/tree/v11.8.2#cookies.

```js
import got from 'got';
import { CookieJar } from 'tough-cookie';
import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

const client = got.extend({
  agent: {
    http: new HttpCookieAgent({ cookies: { jar } }),
    https: new HttpsCookieAgent({ cookies: { jar } }),
  },
});

await client('https://example.com');
```

#### `superagent`

:warning: `superagent` supports cookies by default. You may not need `http-cookie-agent`.

See https://github.com/visionmedia/superagent/blob/v6.1.0/docs/index.md#saving-cookies.

```js
import superagent from 'superagent';
import { CookieJar } from 'tough-cookie';
import { MixedCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();
const mixedAgent = new MixedCookieAgent({ cookies: { jar } });

const client = superagent.agent().use((req) => req.agent(mixedAgent));

await client.get('https://example.com');
```

#### `request`

:warning: `request` supports cookies by default. You may not need `http-cookie-agent`.

See https://github.com/request/request/tree/v2.88.1#examples.

```js
import request from 'request';
import { CookieJar } from 'tough-cookie';
import { MixedCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

const client = request.defaults({
  agent: new MixedCookieAgent({ cookies: { jar } }),
});

client.get('https://example.com', (_err, _res) => {
  // ...
});
```

#### `needle`

```js
import needle from 'needle';
import { CookieJar } from 'tough-cookie';
import { MixedCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

await needle('get', 'https://example.com', {
  agent: new MixedCookieAgent({ cookies: { jar } }),
});
```

#### `phin`

```js
import phin from 'phin';
import { CookieJar } from 'tough-cookie';
import { MixedCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

await phin({
  url: 'https://example.com',
  core: {
    agent: new MixedCookieAgent({ cookies: { jar } }),
  },
});
```

#### `@hapi/wreck`

```js
import Wreck from '@hapi/wreck';
import { CookieJar } from 'tough-cookie';
import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';

const jar = new CookieJar();

const client = Wreck.defaults({
  agents: {
    http: new HttpCookieAgent({ cookies: { jar } }),
    https: new HttpsCookieAgent({ cookies: { jar } }),
    httpsAllowUnauthorized: new HttpsCookieAgent({ cookies: { jar } }),
  },
});

await client.get('https://example.com');
```

#### `urllib`

```js
import { request, setGlobalDispatcher } from 'urllib';
import { CookieJar } from 'tough-cookie';
import { CookieAgent } from 'http-cookie-agent/undici';

const jar = new CookieJar();
const agent = new CookieAgent({ cookies: { jar } });
setGlobalDispatcher(agent);

await request('https://example.com');
```

### Using with another Agent library

If you want to use another Agent library, wrap the agent in `createCookieAgent`.

```js
import https from 'node:https';

import { HttpsAgent as KeepAliveAgent } from 'agentkeepalive';
import { CookieJar } from 'tough-cookie';
import { createCookieAgent } from 'http-cookie-agent/http';

const Agent = createCookieAgent(KeepAliveAgent);

const jar = new CookieJar();
const agent = new Agent({ cookies: { jar } });

https.get('https://example.com', { agent }, (res) => {
  // ...
});
```

#### `undici`

If you want to use another undici Agent library, use `cookie` with the compose method.

```js
import { fetch, ProxyAgent } from 'undici';
import { CookieJar } from 'tough-cookie';
import { cookie } from 'http-cookie-agent/undici';

const jar = new CookieJar();
const agent = new ProxyAgent({
  /* ... */
}).compose(cookie({ jar }));

await fetch('https://example.com', { dispatcher: agent });
```

## Contributing

PRs accepted.

## License

[MIT (c) 3846masa](../LICENSE)

---
_Source: https://npm.io/package/http-cookie-agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._