🍪 fetch-cookie

Decorator for a fetch function to support automatic cookie storage and population.

Migrating from v1

Description

fetch-cookie wraps around a fetch function and intercepts request options and response objects to store received cookies and populate request with the appropriate cookies.

This library is developed with Node.js and fetch polyfill libraries such as node-fetch in mind, since the browser version is supposed to let a way to include cookies in requests. Compatibility may not be guaranteed but as long as your library implements the Fetch standard you should be fine. In case of incompatibilities, please create a new issue.

Internally the plugin uses a cookie jar. You can insert your own (details below) but tough-cookie is preferred.

Usage

With Node.js 18.3.0 and greater, using the native global fetch function:

1import makeFetchCookie from 'fetch-cookie'
2
3const fetchCookie = makeFetchCookie(fetch)

Or with node-fetch:

1import nodeFetch from 'node-fetch'
2import fetchCookie from 'fetch-cookie'
3
4const fetch = fetchCookie(nodeFetch)

Accessing the cookie jar

If you need to manipulate the cookie jar directly:

1import makeFetchCookie from 'fetch-cookie'
2
3const fetchCookie = makeFetchCookie(fetch)
4
5const cookie = await fetchCookie.cookieJar.getCookieString(url)
6
7fetchCookie.cookieJar.setCookie(cookie, url)

Custom cookie jar

If you want to customize the internal cookie jar instance (for example, with a custom store), you can inject it as a second argument:

1import makeFetchCookie from 'fetch-cookie'
2
3const fetchCookie = makeFetchCookie(fetch, new makeFetchCookie.toughCookie.CookieJar())

Here, we expose the tough-cookie version that we depend on internally so you can just reuse it and don't end up accidentally bundling two different versions. That being said you can use any version of tough-cookie here, or even any compatible cookie jar.

This enables you to create multiple fetch-cookie instances that use different cookie jars, essentially two different HTTP clients with different login sessions on you backend (for example).

All calls to fetch will store and send back cookies according to the URL.

If you use a cookie jar that is not tough-cookie, keep in mind that it must implement this interface to be compatible:

1interface CookieJar {
2  getCookieString(currentUrl: string): Promise<string>
3  setCookie(cookieString: string, currentUrl: string, opts: { ignoreError: boolean }): Promise
4}

Custom cookie jar with options

If you don't want a custom store and just want to pass tough-cookie options, e.g. to allow cookies on localhost:

1import makeFetchCookie from 'fetch-cookie'
2
3const fetchCookie = makeFetchCookie(fetch, new makeFetchCookie.toughCookie.CookieJar(undefined, {
4  allowSpecialUseDomain: true
5}))

Or with a custom store as well:

1import makeFetchCookie from 'fetch-cookie'
2import FileCookieStore from 'file-cookie-store'
3
4const store = new FileCookieStore('cookies.txt')
5
6const fetchCookie = makeFetchCookie(fetch, new makeFetchCookie.toughCookie.CookieJar(store, {
7  allowSpecialUseDomain: true
8}))

Ignoring errors

All errors when setting cookies are ignored by default. You can make it throw errors in cookies by passing a third argument ignoreError (defaulting to true).

1import makeFetchCookie from 'fetch-cookie'
2
3const fetchCookie = makeFetchCookie(fetch, new makeFetchCookie.toughCookie.CookieJar(), false)

When set to false, fetch-cookie will throw when an error occurs in setting cookies and breaks the request and execution.

Otherwise, it silently ignores errors and continues to make requests/redirections.

Max redirects

Because we need to do our own redirect implementation, the way to configure the max redirects is not going to be that of your chosen fetch implementation, but custom to fetch-cookie.

We read a maxRedirect parameter for that. The default is 20.

1import makeFetchCookie from 'fetch-cookie'
2
3const fetchCookie = makeFetchCookie(fetch)
4
5await fetchCookie(url, { maxRedirect: 10 })

Cookies on redirects

In order to handle cookies on redirects, we force the redirect parameter to manual, and handle the redirections internally (according to the original redirect value) instead of leaving it to the upstream fetch implementation.

This allows us to hook into the redirect logic in order to store and forward cookies accordingly.

This is useful for example when a login page sets a session cookie and redirects to another page.

Migrating from v1

The only breaking change with v2 is that the node-fetch wrapper (that was handling redirects only with node-fetch nonstandard APIs) was dropped and the redirects are now always handled by the main export.

1// If you were doing
2const fetchCookie = require('fetch-cookie/node-fetch')
3
4// Change it to
5const fetchCookie = require('fetch-cookie')
6
7// Or
8import fetchCookie from 'fetch-cookie'

This also means that if you were not using the node-fetch wrapper and were happy about cookies not being included in redirects, cookies are now going to be stored and sent in redirects as well like they would in the browser.

Development

1# Install dependencies
2npm ci
3
4# Allows to test node-fetch v2 as well as node-fetch v3
5npm --prefix test/node_modules/node-fetch-2 ci
6
7# Allows to test against Undici by removing the blacklisting of `Set-Cookie` headers
8npm run patch-undici
9
10npm run lint
11npm run type-check
12
13# Generates code in `esm` and `cjs` directories
14npm run build
15
16# Run tests (depends on the built code)
17npm test
18
19# Generate type declarations in the `types` directory
20npm run type-declarations

Credits

• 🥰 All the contributors to fetch-cookie!
• 😍 node-fetch for the redirect logic that we carefully mimic (sadly reimplementing this code was the only way to support cookies in redirects).