fetch-h2

library3.0.2jsnpmunverified

fetch-h2 is a robust Node.js implementation of the standard Fetch API, providing a familiar, browser-like interface for making HTTP requests within a Node.js environment. It transparently handles both HTTP/1.1 and HTTP/2 connections, automatically negotiating the protocol via ALPN for `https://` URLs, and defaulting to HTTP/1.1 for `http://` unless `http2://` is explicitly used for plain-text HTTP/2 (h2c). The library is currently stable at version 3.0.2 and receives regular maintenance, including bug fixes and dependency updates. Key differentiators include its close adherence to the Fetch API standard, transparent socket re-use and session management, built-in in-memory cookie support per context, and automatic decoding of `br`, `gzip`, and `deflate` encodings. It offers a higher-level, more developer-friendly abstraction for HTTP/2 client requests in Node.js compared to the lower-level native `http2` module. Since version 3.0.0, it requires Node.js 12 or newer.

http-networking web-framework

npm install fetch-h2

github ↗package ↗

INSTALL

IMPORT

SIG · FETCH-H2

fetch-h2

http-networkingjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetch

✓ import { fetch } from 'fetch-h2'

✗ const fetch = require('fetch-h2')

fetch-h2 is primarily designed for ESM usage since v3, though CJS might still work. Named imports are standard.

setup

✓ import { setup } from 'fetch-h2'

✗ import setup from 'fetch-h2'

All exports are named exports, including configuration functions like `setup`.

AbortController

✓ import { AbortController } from 'fetch-h2'

Used for request cancellation and managing timeouts, mirroring the browser's AbortController API.

Response

✓ import { Response } from 'fetch-h2'

The Response class is directly exported, consistent with the Fetch API specification.

Demonstrates a basic GET request using `fetch`, handling the response, and error conditions, including custom headers.

import { fetch } from 'fetch-h2'; async function fetchData() { const targetUrl = process.env.API_URL ?? 'https://httpbin.org/get'; try { const response = await fetch(targetUrl, { headers: { 'User-Agent': 'fetch-h2-checklist-day-example/1.0' } }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); console.log('Successfully fetched data:', data.url, data.headers['User-Agent']); console.log('Headers:', response.headers.get('Content-Type')); } catch (error) { console.error('Failed to fetch:', error.message); } } fetchData();

Debug

Known issues

breakingVersion 3.0.0 and above requires Node.js 12 or newer. Older Node.js versions (e.g., Node 10) are not supported.

fix

Upgrade your Node.js environment to version 12 or higher, or use an older version of fetch-h2 (e.g., <3.0.0) if Node 10 support is critical.

affects: >=3.0.0

breakingPrevious versions (1.x, 2.x) had their own Node.js engine requirements (1.0.0 required Node 10, 2.0.0 required Node 10.4). Always check the engine requirement for your specific version.

fix

Consult the `engines` field in the package.json or the release notes for the exact Node.js version compatibility.

affects: >=1.0.0

gotchaCookies are handled per-context and stored only in-memory. They are not persisted to disk or automatically shared across different application runs.

fix

If persistent cookie storage or cross-process sharing is required, manually retrieve cookies from `CookieJar` and manage them outside the library.

affects: >=1.0.0

gotchaBy default, `fetch-h2` will use HTTP/1.1 for `http://` URLs. To explicitly use plain-text HTTP/2 (h2c), you must prefix the URL with `http2://`.

fix

For h2c connections, ensure your URL starts with `http2://` (e.g., `http2://localhost:8080`). For HTTPS, ALPN negotiation handles protocol selection.

affects: >=2.0.0

gotchaTimeouts are internally implemented using `AbortController` signals. When a timeout occurs, a `TimeoutError` (which extends `AbortError`) is thrown.

fix

Catch `TimeoutError` specifically if you need to differentiate timeout errors from other abort signals. Otherwise, catching `AbortError` will cover both.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: fetch is not a function

Attempting to use `require()` for the `fetch` function in a CommonJS module context, which is typically an ESM-only export.

fix

Use ESM `import { fetch } from 'fetch-h2'` in a module with `"type": "module"` in package.json or with an `.mjs` extension.

TimeoutError: The operation timed out

The HTTP request exceeded the configured timeout duration, leading to an automatic cancellation.

fix

Increase the timeout value in the `init` object (e.g., `{ timeout: 10000 }`) or investigate network/server performance issues.

Error: HTTP error! status: 404

The requested resource was not found on the server, or another non-2xx/3xx status code was returned indicating an application-level error.

fix

Check the URL, verify the resource exists, and ensure the server is configured to return expected status codes. Add specific error handling for different HTTP statuses.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/grantila/fetch-h2 ↗

packagehttps://www.npmjs.com/package/fetch-h2 ↗