Axios Middleware Service

Common errors

• TypeError: Class extends value undefined is not a constructor or null

  cause Attempting to extend the `HttpMiddleware` base class after upgrading to `axios-middleware` v0.3.0 or later, where this class was removed.
  fix Remove the `extends HttpMiddleware` clause from your middleware class definition. Implement handler methods directly or use plain objects for middleware.

• Property 'handleRequestError' does not exist on type '...' or 'middleware.use' expects a different type of handler.

  cause Using old `handle` prefixed method names (e.g., `handleRequestError`) after upgrading to `axios-middleware` v0.1.3 or later.
  fix Update method names from `handleX` to `onX` (e.g., `handleRequestError` becomes `onRequestError`, `handleResponse` becomes `onResponse`).

• TypeError: Cannot read properties of undefined (reading 'interceptors') or TypeError: axiosInstance.interceptors is undefined

  cause Incorrectly initializing `axios-middleware` with a non-Axios instance or a misconfigured Axios instance.
  fix Ensure `axiosMiddleware` is instantiated with a valid `axios` instance created using `axios.create()` or the global `axios` object.

Warnings

• breaking The `HttpMiddleware` base class was removed in v0.3.0. Projects inheriting from this class will break.
  Fix: Refactor middleware classes to no longer extend `HttpMiddleware`. Instead, use plain objects or classes implementing the handler methods (`onRequest`, `onResponse`, etc.) directly with `middleware.use()`.
• breaking Method prefixes for middleware handlers changed from `handle` to `on` in v0.1.3. For example, `handleRequestError` became `onRequestError`.
  Fix: Rename middleware handler methods (e.g., `handleRequest` to `onRequest`, `handleResponseError` to `onResponseError`).
• gotcha This package has reached its End of Life (EOL) with version 0.4.0. The maintainer explicitly states it will no longer be maintained due to breaking changes in Axios and general shifts in recommended HTTP client practices.
  Fix: It is strongly recommended to migrate to an alternative solution or directly use Axios's built-in interceptors. Continuing to use this package may lead to compatibility issues with newer Axios versions and lack of security updates.
• gotcha The package's peer dependency for `axios` is `>=0.17.1 <1.2.0`. Using `axios-middleware` with Axios v1.2.0 or newer versions (e.g., Axios v2.x) will likely lead to incompatibility issues and unexpected behavior.
  Fix: Either downgrade your `axios` version to match the peer dependency range (`<1.2.0`) or, preferably, migrate away from `axios-middleware` to a maintained solution that supports modern Axios versions or use Axios's native interceptors.

Install

• npm install axios-middleware npm
• yarn add axios-middleware yarn
• pnpm add axios-middleware pnpm

Imports

• default
  wrong:

  import { axiosMiddleware } from 'axios-middleware';

  correct:

  import axiosMiddleware from 'axios-middleware';

  The library primarily exports a default class/function to initialize the middleware service.
• AxiosMiddleware
  wrong:

  import { AxiosMiddleware } from 'axios-middleware';

  correct:

  import axiosMiddleware from 'axios-middleware';
  const middleware = new axiosMiddleware(client);

  While often used as a class, it's a default export, so the instantiation pattern is `new axiosMiddleware(...)` after a default import.
• Middleware Handler Object

  middleware.use({
    onRequest(config) { /* ... */ },
    onResponse(response) { /* ... */ }
  });

  Middleware logic is defined via an object passed to the `use` method, containing methods like `onRequest`, `onResponse`, `onRequestError`, `onResponseError`, and `onSync`.

Quickstart

This quickstart demonstrates how to set up `axios-middleware` with an Axios instance, register request and response interceptors, and then make API calls, showcasing both success and error handling.

import axios from 'axios';
import axiosMiddleware from 'axios-middleware';

const client = axios.create({
  baseURL: 'https://jsonplaceholder.typicode.com',
  timeout: 5000
});

const middleware = new axiosMiddleware(client);

middleware.use({
  onRequest(config) {
    console.log('[Middleware] Request sent:', config.method?.toUpperCase(), config.url);
    // Example: Add an authorization header
    config.headers['X-Custom-Auth'] = 'my-secret-token';
    return config;
  },
  onResponse(response) {
    console.log('[Middleware] Response received for', response.config.url, 'Status:', response.status);
    return response;
  },
  onRequestError(error) {
    console.error('[Middleware] Request error:', error.message);
    return Promise.reject(error);
  },
  onResponseError(error) {
    console.error('[Middleware] Response error for', error.config.url, 'Status:', error.response?.status, error.message);
    return Promise.reject(error);
  }
});

// Make a request using the configured Axios instance
client.get('/posts/1')
  .then(response => {
    console.log('API Response Data:', response.data);
  })
  .catch(error => {
    console.error('API Call Failed:', error.message);
  });

// Example of a request that might trigger an error (e.g., non-existent endpoint)
client.get('/nonexistent-path')
  .catch(error => {
    console.error('Non-existent path call failed, caught by application:', error.message);
  });