http-cookie-agent

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 another Agent library
• Contributing
• License

Install

npm install http-cookie-agent tough-cookie

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

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

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 });

undici

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. In this case, the cookie() must be placed at the beginning of the interceptors.

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

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

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

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.

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.

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.

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

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

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

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

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.

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.

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

Similar packages

Other packages similar to http-cookie-agent

axios

Axios is a popular HTTP client for Node.js and the browser. It supports automatic cookie handling when used with the `withCredentials` option and a custom adapter. Compared to http-cookie-agent, Axios provides a more comprehensive HTTP client with built-in support for promises and a wide range of features beyond cookie management.

request

Request is a simplified HTTP client for Node.js with built-in cookie support via the `jar` option. While it is no longer actively maintained, it was widely used for its simplicity and ease of use. Compared to http-cookie-agent, Request offers a more straightforward API for making HTTP requests with cookie management.

node-fetch

Node-fetch is a lightweight module that brings `window.fetch` to Node.js. It can be used with cookie management libraries like `tough-cookie` to handle cookies. Compared to http-cookie-agent, node-fetch is more focused on providing a Fetch API implementation, requiring additional setup for cookie management.