HTTP Cookie Agent

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

Table of Contents

• Install
• Usage
  • Supported libraries
  • Using with an asynchronous Cookie store
  • Using with another Agent library
• Contributing
• License

Install

1npm install http-cookie-agent tough-cookie

When you want to use Node.js global fetch (aka. undici), you should install undici additionally.

1npm install undici

Usage

See also examples for more details.

Supported libraries

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

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

Node.js global fetch

http-cookie-agent supports global fetch since Node.js v18.2.0.

1import { CookieJar } from 'tough-cookie';
2import { CookieAgent } from 'http-cookie-agent/undici';
3
4const jar = new CookieJar();
5const agent = new CookieAgent({ cookies: { jar } });
6
7await fetch('https://example.com', { dispatcher: agent });

undici

1import { fetch } from 'undici';
2import { CookieJar } from 'tough-cookie';
3import { CookieAgent } from 'http-cookie-agent/undici';
4
5const jar = new CookieJar();
6const agent = new CookieAgent({ cookies: { jar } });
7
8await fetch('https://example.com', { dispatcher: agent });

node:http / node:https

1import https from 'node:https';
2
3import { CookieJar } from 'tough-cookie';
4import { HttpsCookieAgent } from 'http-cookie-agent/http';
5
6const jar = new CookieJar();
7const agent = new HttpsCookieAgent({ cookies: { jar } });
8
9https.get('https://example.com', { agent }, (res) => {
10  // ...
11});

axios

1import axios from 'axios';
2import { CookieJar } from 'tough-cookie';
3import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7const client = axios.create({
8  httpAgent: new HttpCookieAgent({ cookies: { jar } }),
9  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
10});
11
12await client.get('https://example.com');

node-fetch

1import fetch from 'node-fetch';
2import { CookieJar } from 'tough-cookie';
3import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7const httpAgent = new HttpCookieAgent({ cookies: { jar } });
8const httpsAgent = new HttpsCookieAgent({ cookies: { jar } });
9
10await fetch('https://example.com', {
11  agent: ({ protocol }) => {
12    return protocol === 'https:' ? httpsAgent : httpAgent;
13  },
14});

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.

1import got from 'got';
2import { CookieJar } from 'tough-cookie';
3import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7const client = got.extend({
8  agent: {
9    http: new HttpCookieAgent({ cookies: { jar } }),
10    https: new HttpsCookieAgent({ cookies: { jar } }),
11  },
12});
13
14await 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.

1import superagent from 'superagent';
2import { CookieJar } from 'tough-cookie';
3import { MixedCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6const mixedAgent = new MixedCookieAgent({ cookies: { jar } });
7
8const client = superagent.agent().use((req) => req.agent(mixedAgent));
9
10await 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.

1import request from 'request';
2import { CookieJar } from 'tough-cookie';
3import { MixedCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7const client = request.defaults({
8  agent: new MixedCookieAgent({ cookies: { jar } }),
9});
10
11client.get('https://example.com', (_err, _res) => {
12  // ...
13});

needle

1import needle from 'needle';
2import { CookieJar } from 'tough-cookie';
3import { MixedCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7await needle('get', 'https://example.com', {
8  agent: new MixedCookieAgent({ cookies: { jar } }),
9});

phin

1import phin from 'phin';
2import { CookieJar } from 'tough-cookie';
3import { MixedCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7await phin({
8  url: 'https://example.com',
9  core: {
10    agent: new MixedCookieAgent({ cookies: { jar } }),
11  },
12});

@hapi/wreck

1import Wreck from '@hapi/wreck';
2import { CookieJar } from 'tough-cookie';
3import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/http';
4
5const jar = new CookieJar();
6
7const client = Wreck.defaults({
8  agents: {
9    http: new HttpCookieAgent({ cookies: { jar } }),
10    https: new HttpsCookieAgent({ cookies: { jar } }),
11    httpsAllowUnauthorized: new HttpsCookieAgent({ cookies: { jar } }),
12  },
13});
14
15await client.get('https://example.com');

urllib

1import { request, setGlobalDispatcher } from 'urllib';
2import { CookieJar } from 'tough-cookie';
3import { CookieClient } from 'http-cookie-agent/undici';
4
5const jar = new CookieJar();
6const agent = new CookieAgent({ cookies: { jar } });
7setGlobalDispatcher(agent);
8
9await request('https://example.com');

Using with another Agent library

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

1import https from 'node:https';
2
3import { HttpsAgent as KeepAliveAgent } from 'agentkeepalive';
4import { CookieJar } from 'tough-cookie';
5import { createCookieAgent } from 'http-cookie-agent/http';
6
7const Agent = createCookieAgent(KeepAliveAgent);
8
9const jar = new CookieJar();
10const agent = new Agent({ cookies: { jar } });
11
12https.get('https://example.com', { agent }, (res) => {
13  // ...
14});

undici

If you want to use another undici Agent library, use CookieClient via factory function.

1import { fetch, ProxyAgent } from 'undici';
2import { CookieJar } from 'tough-cookie';
3import { CookieClient } from 'http-cookie-agent/undici';
4
5const jar = new CookieJar();
6const agent = new ProxyAgent({
7  factory: (origin, opts) => {
8    return new CookieClient(origin, {
9      ...opts,
10      cookies: { jar },
11    });
12  },
13});
14
15await fetch('https://example.com', { dispatcher: agent });

If you want to use another undici Client library, wrap the client in createCookieClient.

1import { fetch, Agent, MockClient } from 'undici';
2import { CookieJar } from 'tough-cookie';
3import { createCookieClient } from 'http-cookie-agent/undici';
4
5const CookieClient = createCookieClient(MockClient);
6
7const jar = new CookieJar();
8const agent = new Agent({
9  factory: (origin, opts) => {
10    return new CookieClient(origin, {
11      ...opts,
12      cookies: { jar },
13    });
14  },
15});
16
17await fetch('https://example.com', { dispatcher: agent });

Contributing

PRs accepted.

License

MIT (c) 3846masa