{"id":13313,"library":"http2-wrapper","title":"HTTP/2 Client with familiar HTTPS API","description":"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.","status":"active","version":"2.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/szmarczak/http2-wrapper","tags":["javascript","http2","https","http","request","typescript"],"install":[{"cmd":"npm install http2-wrapper","lang":"bash","label":"npm"},{"cmd":"yarn add http2-wrapper","lang":"bash","label":"yarn"},{"cmd":"pnpm add http2-wrapper","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For CommonJS, use `const http2 = require('http2-wrapper');`. This library exports its API as a namespace object, not a default export.","wrong":"import http2 from 'http2-wrapper';","symbol":"http2","correct":"import * as http2 from 'http2-wrapper';"},{"note":"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.","symbol":"request","correct":"import { request } from 'http2-wrapper';"},{"note":"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`.","wrong":"import auto from 'http2-wrapper';","symbol":"auto","correct":"import { auto } from 'http2-wrapper';"}],"quickstart":{"code":"import { request } from 'http2-wrapper';\n\nconst options = {\n\thostname: 'nghttp2.org',\n\tprotocol: 'https:',\n\tpath: '/httpbin/post',\n\tmethod: 'POST',\n\theaders: {\n\t\t'content-length': 6\n\t}\n};\n\nconst req = request(options, response => {\n\tconsole.log('statusCode:', response.statusCode);\n\tconsole.log('headers:', response.headers);\n\n\tconst body = [];\n\tresponse.on('data', chunk => {\n\t\tbody.push(chunk);\n\t});\n\tresponse.on('end', () => {\n\t\tconsole.log('body:', Buffer.concat(body).toString());\n\t});\n});\n\nreq.on('error', console.error);\n\nreq.write('123');\nreq.end('456');\n\n// Expected output (statusCode: 200, headers and body containing '123456')","lang":"typescript","description":"Demonstrates how to make a basic HTTP/2 POST request using the `request` API, similar to Node.js's native `https.request`."},"warnings":[{"fix":"Update request options, replacing `session` with `tlsSession` (e.g., `{ tlsSession: yourTlsSession }`).","message":"The `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.","severity":"breaking","affected_versions":">=2.0.0"},{"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 })`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","cause":"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).","error":"TypeError: http2.request is not a function"},{"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.","cause":"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.","error":"Error: Protocol \"http:\" not supported. Expected \"https:\" for ALPN."},{"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.","cause":"Certificate validation failure, often due to self-signed certificates, outdated root CAs, or corporate proxies intercepting TLS traffic.","error":"UNABLE_TO_VERIFY_LEAF_SIGNATURE"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}