or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-axios-cookiejar-support

Add tough-cookie support to axios.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/axios-cookiejar-support@6.0.x

To install, run

npx @tessl/cli install tessl/npm-axios-cookiejar-support@6.0.0

index.mddocs/

axios-cookiejar-support

Overview

axios-cookiejar-support is a TypeScript library that adds tough-cookie support to axios HTTP client for Node.js applications. It enables persistent cookie management across HTTP requests by wrapping axios instances with a request interceptor that automatically configures HTTP/HTTPS agents with cookie jar support. The library maintains cookie state through CookieJar instances from tough-cookie and provides a browser-compatible noop implementation.

Package Information

  • Name: axios-cookiejar-support
  • Type: npm package
  • Language: TypeScript (with JavaScript support)
  • Installation: npm install axios tough-cookie axios-cookiejar-support
  • Node.js: >= 20.0.0
  • Browser: Supported via noop implementation

Core Imports

ESM (recommended)

import { wrapper } from 'axios-cookiejar-support';
import { CookieJar } from 'tough-cookie';
import axios from 'axios';

CommonJS

const { wrapper } = require('axios-cookiejar-support');
const { CookieJar } = require('tough-cookie');
const axios = require('axios');

Basic Usage

The most common usage pattern is to create a cookie jar and wrap an axios instance:

import axios from 'axios';
import { wrapper } from 'axios-cookiejar-support';
import { CookieJar } from 'tough-cookie';

// Create a cookie jar
const jar = new CookieJar();

// Create and wrap an axios instance
const client = wrapper(axios.create({ jar }));

// Use the client - cookies will be automatically managed
await client.get('https://example.com');

You can also wrap the static axios object:

import axios from 'axios';
import { wrapper } from 'axios-cookiejar-support';
import { CookieJar } from 'tough-cookie';

// Wrap the static axios
wrapper(axios);

// Create a cookie jar
const jar = new CookieJar();

// Use axios directly with jar config
await axios.get('https://example.com', { jar });

Architecture

axios-cookiejar-support uses an interceptor-based architecture that integrates seamlessly with axios:

  • Request Interceptor: Automatically configures HTTP/HTTPS agents with cookie jar support when a jar config is present
  • Agent Management: Creates HttpCookieAgent and HttpsCookieAgent instances from the http-cookie-agent library
  • Symbol-based Tracking: Uses internal symbols to prevent conflicts with user-defined agents and ensure idempotent wrapping
  • Wrapper Function: The main wrapper function adds the interceptor to both instances and the create method for comprehensive coverage
  • Platform Detection: Automatically provides browser-compatible noop implementation via package.json exports

Capabilities

Axios Wrapper

The main function that adds cookie jar support to axios instances.

function wrapper<T extends AxiosStatic | AxiosInstance>(axios: T): T;

Parameters:

  • axios (AxiosStatic | AxiosInstance): Either the static axios object or an axios instance

Returns:

  • T: The same axios object/instance with cookie jar interceptor added

Generic Type:

  • T extends AxiosStatic | AxiosInstance: Preserves the exact type of the input axios

Behavior:

  • Adds request interceptor for cookie jar support
  • Idempotent: calling wrapper multiple times on the same instance has no additional effect
  • For static axios, also wraps the create method to ensure new instances get cookie support
  • Configures HTTP/HTTPS agents with cookie jar when jar is present in request config

Example:

import axios from 'axios';
import { wrapper } from 'axios-cookiejar-support';
import { CookieJar } from 'tough-cookie';

const jar = new CookieJar();
const client = wrapper(axios.create({ jar }));

// The client now supports cookie management
await client.get('https://httpbin.org/cookies/set/session_id/abc123');
await client.get('https://httpbin.org/cookies'); // Will include the session_id cookie

Type Definitions

AxiosRequestConfig Extension

declare module 'axios' {
  interface AxiosRequestConfig {
    jar?: CookieJar;
  }
}

Extends axios request configuration to include optional cookie jar support.

Properties:

  • jar?: CookieJar: Optional tough-cookie CookieJar instance for cookie management

AxiosInterceptorManager Extension

declare module 'axios' {
  interface AxiosInterceptorManager {
    handlers: Array<{
      fulfilled: (...args: unknown[]) => unknown;
      rejected: (...args: unknown[]) => unknown;
      runWhen: unknown;
      synchronous: unknown;
    }>;
  }
}

Extends axios interceptor manager to expose handlers array (used internally for idempotent wrapping).

Platform Support

Node.js

Full functionality with HTTP/HTTPS agent configuration for cookie management.

Browser

Provides a noop implementation since browsers handle cookies automatically:

// Browser implementation (automatic via package.json exports)
export function wrapper(axios) {
  return axios; // No-op, returns axios unchanged
}

Error Handling

The library throws specific errors for configuration issues:

Legacy Boolean Jar Error

// This will throw an error
const config = { jar: true }; // Invalid since v2.0.0
// Error: "config.jar does not accept boolean since axios-cookiejar-support@2.0.0."

Agent Conflict Error

import https from 'https';

// This will throw an error if jar is also specified
const config = { 
  jar: new CookieJar(),
  httpsAgent: new https.Agent() // Conflicts with cookie jar agent
};
// Error: "axios-cookiejar-support does not support for use with other http(s).Agent."

Advanced Usage

Per-Request Cookie Jars

You can use different cookie jars for different requests:

const jar1 = new CookieJar();
const jar2 = new CookieJar();
const client = wrapper(axios.create());

// Use different jars per request
await client.get('https://site1.com', { jar: jar1 });
await client.get('https://site2.com', { jar: jar2 });

Session Management

Ideal for maintaining session state across requests:

const jar = new CookieJar();
const client = wrapper(axios.create({ jar }));

// Login and establish session
await client.post('https://example.com/login', {
  username: 'user',
  password: 'pass'
});

// Subsequent requests will include session cookies
const response = await client.get('https://example.com/profile');

Type Safety

The library provides full TypeScript support with proper generic type preservation:

import axios, { AxiosInstance } from 'axios';
import { wrapper } from 'axios-cookiejar-support';

const instance: AxiosInstance = axios.create();
const wrappedInstance: AxiosInstance = wrapper(instance); // Type preserved

// All original axios methods and properties available
wrappedInstance.defaults.timeout = 5000;
wrappedInstance.interceptors.response.use(/* ... */);