fetch-intercept

2.4.0 verified Sat Apr 25 auth: no javascript

A lightweight library to intercept and modify fetch requests and responses, inspired by Angular HTTP interceptors. Version 2.4.0 is the latest stable release, with infrequent updates. It monkey-patches the global fetch function to allow addition of request/response interceptors in browser, Node, and WebWorker environments. Unlike other interceptors, it uses a simple register/unregister pattern and supports TypeScript definitions, making it easy to add logging, authentication headers, or error handling without modifying fetch calls directly. It requires fetch to be available (polyfill suggested for older environments).

Common errors

error TypeError: Failed to fetch ↓

cause Interceptor does not return proper [url, config] array or returns undefined.

fix

Ensure request interceptor returns a tuple: return [url, config];

error fetchInterceptor.register is not a function ↓

cause Incorrect import syntax (e.g., named import instead of default).

fix

Use default import: import fetchIntercept from 'fetch-intercept';

error Cannot read properties of undefined (reading 'headers') ↓

cause Config object is undefined when no options are passed to fetch.

fix

Use optional chaining: config?.headers, or provide default empty object: const newConfig = config || {};

Warnings

gotcha fetch-intercept modifies the global fetch. Calling register() multiple times stacks interceptors; unregister() removes the last registered interceptor. ↓

fix Keep track of unregister functions and call them in reverse order to fully clean up.

gotcha The request interceptor must return an array of [url, config] or undefined to retain original. Returning null or other types may break fetch. ↓

fix Always return [url, config] from request interceptor, even if unchanged.

gotcha fetch-intercept does not work with AbortController in older versions; abort signals may be lost in interceptors. ↓

fix Upgrade to version 2.x for better AbortController support, or manually handle signal in config.

deprecated The library has not been updated for several years; future browser fetch changes may break compatibility. ↓

fix Consider alternative interceptors like 'undici' or custom wrappers if active maintenance is required.

Install

npm install fetch-intercept

yarn add fetch-intercept

pnpm add fetch-intercept

Imports

default

wrong

import { fetchIntercept } from 'fetch-intercept';

correct

import fetchIntercept from 'fetch-intercept';

The package exports a default object, not named exports. Use default import.

register

wrong

import { register } from 'fetch-intercept';

correct

import fetchIntercept from 'fetch-intercept';
const unregister = fetchIntercept.register({...});

unregister

wrong

import { unregister } from 'fetch-intercept';

correct

import fetchIntercept from 'fetch-intercept';
const unregister = fetchIntercept.register({...});
unregister();

unregister is a function returned by register(), not a named export.

Quickstart

Demonstrates registering interceptors to modify fetch requests and responses, then unregistering.

import fetchIntercept from 'fetch-intercept';

// Register interceptors
const unregister = fetchIntercept.register({
  request: function (url, config) {
    // Modify the request: add headers
    const newConfig = { ...config, headers: { ...config?.headers, 'X-Interceptor': 'true' } };
    return [url, newConfig];
  },
  response: function (response) {
    // Modify the response: log status
    console.log('Response status:', response.status);
    return response;
  },
});

// Use fetch normally
fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(data => console.log(data))
  .finally(() => unregister()); // Clean up

export {}; // Ensure module context for TypeScript