Registry / http-networking / http2-wrapper

http2-wrapper

library2.2.1jsnpmunverified

http2-wrapper is a Node.js library that provides an HTTP/2 client using an API familiar to users of Node's built-in `https` module. It allows existing codebases that rely on the HTTP/1 API to transparently support HTTP/2 without extensive rewrites. The current stable version is 2.2.1, with releases occurring as needed for bug fixes and minor improvements, typically every few weeks as seen in recent changelogs. A key differentiator is its ability to bridge HTTP/1-style agents with native HTTP/2 streams, enabling HTTP/2 support in modules designed for HTTP/1. While the maintainer recommends using the native `http2` module directly for new projects, `http2-wrapper` excels as a compatibility layer or when custom HTTP/2 agents are needed. It ships with TypeScript types, facilitating safer development in TypeScript environments.

http-networking serialization

npm install http2-wrapper

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP2-WRAPPER

http2-wrapper

http-networkingjavascriptv2.2.1

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.

http2

✓ import * as http2 from 'http2-wrapper';

✗ import http2 from 'http2-wrapper';

For CommonJS, use `const http2 = require('http2-wrapper');`. This library exports its API as a namespace object, not a default export.

request

✓ import { request } from 'http2-wrapper';

This function mirrors the `http.request` and `https.request` API for making HTTP/2 requests. It's also available as `http2.request` after a namespace import.

auto

✓ import { auto } from 'http2-wrapper';

✗ import auto from 'http2-wrapper';

The `http2.auto` function performs ALPN negotiation to determine the protocol (HTTP/1 or HTTP/2) and returns the appropriate `ClientRequest` instance. It's also available as `http2.auto`.

Demonstrates how to make a basic HTTP/2 POST request using the `request` API, similar to Node.js's native `https.request`.

import { request } from 'http2-wrapper'; const options = { hostname: 'nghttp2.org', protocol: 'https:', path: '/httpbin/post', method: 'POST', headers: { 'content-length': 6 } }; const req = request(options, response => { console.log('statusCode:', response.statusCode); console.log('headers:', response.headers); const body = []; response.on('data', chunk => { body.push(chunk); }); response.on('end', () => { console.log('body:', Buffer.concat(body).toString()); }); }); req.on('error', console.error); req.write('123'); req.end('456'); // Expected output (statusCode: 200, headers and body containing '123456')

Debug

Known issues

breakingThe `session` option, previously used for TLS session management, was renamed to `tlsSession` to improve readability and avoid confusion with other session concepts. Using the old option name will result in it being ignored.

fix

Update request options, replacing `session` with `tlsSession` (e.g., `{ tlsSession: yourTlsSession }`).

affects: >=2.0.0

gotchaThe `timeout` option configured directly on the request options (`http2.request(options)`) only applies to individual HTTP/2 streams. To control the timeout for the underlying HTTP/2 session, a custom Agent instance with its own `timeout` property must be provided to the request.

fix

To set a session timeout, create an `http2.Agent` instance with the desired `timeout` and pass it in the request options: `new http2.Agent({ timeout: 5000 })`.

affects: >=1.0.0

gotchaWhile `http2-wrapper` provides a familiar API for HTTP/2, its primary use case is compatibility for existing HTTP/1-based modules. For new applications or when direct, fine-grained control over native HTTP/2 features is paramount, the maintainer recommends using Node.js's built-in `http2` module directly, as it can offer a simpler API and more advanced features for native HTTP/2 usage.

fix

Evaluate if direct usage of Node.js `http2` module is more suitable for new projects or when maximum control over HTTP/2 protocol specifics is desired.

affects: >=1.0.0

gotchaWhen using `http2.auto`, ALPN (Application-Layer Protocol Negotiation) is performed to dynamically select between HTTP/1 and HTTP/2. Ensure that the target server supports ALPN and the desired protocols, and correctly specify the `protocol` option (e.g., `'https:'`) as ALPN is inherently a TLS extension.

fix

Verify server ALPN configuration and ensure the `protocol` option in your request (e.g., `protocol: 'https:'`) aligns with the expected negotiation. TLS handshake failures or protocol errors often stem from ALPN mismatches.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: http2.request is not a function

Attempting to use `http2.request` with an incorrect import style (e.g., `import http2 from 'http2-wrapper'` which defaults to `undefined` for a non-default export, or incorrect CommonJS usage).

fix

For CommonJS, use `const http2 = require('http2-wrapper');`. For ESM, use `import * as http2 from 'http2-wrapper';` or specifically `import { request } from 'http2-wrapper';`.

Error: Protocol "http:" not supported. Expected "https:" for ALPN.

Using `http2.auto` with a non-secure `protocol` (e.g., `'http:'`) when ALPN, required for HTTP/2, is a TLS extension. HTTP/2 over plain HTTP (h2c) requires explicit server and client configuration.

fix

Change the `protocol` option to `'https:'` for ALPN negotiation, or ensure the server explicitly supports h2c and configure the client accordingly if HTTP/2 over plain HTTP is intended.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

Certificate validation failure, often due to self-signed certificates, outdated root CAs, or corporate proxies intercepting TLS traffic.

fix

For development or trusted internal environments, you can bypass validation with `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'` (use with extreme caution!). For production, provide custom CA certificates via `options.ca` or ensure proper certificate chain.

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/szmarczak/http2-wrapper ↗

packagehttps://www.npmjs.com/package/http2-wrapper ↗