http-client

4.3.1 verified Sat Apr 25 auth: no javascript

A lightweight library for composing HTTP clients using JavaScript's fetch API. Current stable version is 4.3.1, released with moderate cadence. It provides a middleware-based approach to extend and customize fetch behavior, supporting both client and server environments. Key differentiators include full preservation of fetch API capabilities, an extendable middleware API, and identical usage across Node.js and browsers. Unlike heavier alternatives like axios or superagent, http-client leans on the native fetch standard, allowing polyfills such as isomorphic-fetch for environments without global fetch.

Common errors

error TypeError: Failed to fetch ↓

cause No global fetch implementation present (e.g., in Node.js without polyfill).

fix

Install and import isomorphic-fetch: import 'isomorphic-fetch' before using http-client.

error Uncaught TypeError: middleware is not a function ↓

cause Passed an invalid middleware (e.g., undefined) to createFetch.

fix

Ensure each middleware imported correctly and is a function.

error Cannot read property 'body' of undefined ↓

cause JSON parse middleware not applied before accessing response.body.

fix

Add parse('json') middleware to the fetch client stack.

Warnings

gotcha Requires a global fetch polyfill (e.g., isomorphic-fetch) in environments without native fetch (e.g., older Node versions). ↓

fix Install and import a polyfill like isomorphic-fetch before using http-client.

breaking Version 3.x dropped support for Node < 10 and removed deprecated middleware 'headers' in favor of 'accept' and 'auth'. ↓

fix Update to v4.x; replace 'headers' middleware with explicit 'accept' and 'auth' calls.

gotcha Middleware order matters; for example, 'parse' must come after middleware that sets response headers (like 'accept' or 'auth'). ↓

fix Place 'parse' after all middleware that modifies request headers.

deprecated The 'headers' middleware was deprecated in v3.0 and removed in v4.0. ↓

fix Use 'accept' and 'auth' middleware individually.

Install

npm install http-client

yarn add http-client

pnpm add http-client

Imports

createFetch

wrong

const createFetch = require('http-client').createFetch

correct

import { createFetch } from 'http-client'

ESM import is recommended; CommonJS requires destructuring the require.

base

wrong

import base from 'http-client'

correct

import { base } from 'http-client'

base is a named export, not the default.

createStack

wrong

import { createStack } from 'http-client/middleware'

correct

import { createStack } from 'http-client'

All exports are from the main package, no subpath imports.

Quickstart

Creates a typed fetch client with base URL, Accept header, and JSON parsing middleware.

import { createFetch, base, accept, parse } from 'http-client'

const fetch = createFetch(
  base('https://api.example.com'),
  accept('application/json'),
  parse('json')
)

fetch('/users/1')
  .then(response => {
    console.log(response.body) // parsed JSON
  })
  .catch(error => {
    console.error('Request failed:', error)
  })