node-http2

Common errors

• Error: Cannot find module 'http2'

  cause Attempting to `require('http2')` when the current Node.js version does not have the native HTTP/2 module enabled, or an incorrect path is used. Alternatively, if `node-http2` was intended, it might not be installed or resolved correctly.
  fix If intending to use Node.js's native module, ensure your Node.js version is >= 8.0.0 (for experimental) or >= 10.0.0 (for stable) and use `require('node:http2')`. If specifically targeting *this* `node-http2` package, ensure `npm install node-http2` has been run and use `require('node-http2')`.

• TypeError: http2.createServer is not a function

  cause This error often occurs when `require('http2')` resolves to the native Node.js `http2` module, which exposes `createSecureServer` and `createServer` directly but with potentially different arguments or behavior than `node-http2`, or vice-versa.
  fix Explicitly decide which module you intend to use. For the native Node.js module: `const http2 = require('node:http2'); http2.createSecureServer(...)`. For this legacy `node-http2` package: `const http2 = require('node-http2'); http2.createServer(...)`. Pay attention to whether `createSecureServer` (native) or `createServer` (this package) is expected, and the required options.

• SSL_CTX_set_alpn_protos failed

  cause HTTP/2 relies heavily on TLS and ALPN for secure connections. This error can indicate issues with TLS setup, incorrect certificate/key files, or an incompatibility with the Node.js crypto module or OpenSSL version, especially given the age of this library.
  fix Double-check your `key` and `cert` file paths and permissions. Ensure they are valid TLS certificates. If using an older Node.js, update to a newer version (preferably one with native http2 support) to get modern TLS features. If using `node-http2`, ensure Node.js >= 5.0 for ALPN.

Warnings

• breaking This package (`node-http2` by Kaazing) is completely superseded by the native `http2` module included in Node.js core since v8.0.0 (stable in v10.0.0). Using this package in modern Node.js environments will cause dependency conflicts, unexpected behavior, and prevent access to newer HTTP/2 features and performance optimizations. Do not use this package for new development.
  Fix: Migrate to the built-in `node:http2` module. The API is similar but has differences, especially in stream handling. Consult the official Node.js documentation for `node:http2`.
• gotcha The package is no longer maintained. This means it will not receive updates for security vulnerabilities, bug fixes, or compatibility with newer Node.js versions or HTTP/2 specification updates.
  Fix: Avoid using this package in production. If forced to use legacy code, thoroughly audit for known vulnerabilities and consider isolated execution environments.
• gotcha ALPN (Application-Layer Protocol Negotiation) support within this `node-http2` package is explicitly stated to only work for Node.js versions >= 5.0. Earlier Node.js versions may encounter issues establishing HTTP/2 connections.
  Fix: Ensure your Node.js version is 5.0 or higher if using this package, though migrating to the native `node:http2` module is the vastly superior solution.
• deprecated The original `molnarg/node-http2` repository (from which this package was forked) explicitly marked itself as deprecated, advising users to switch to the Node.js built-in `http2` module. This deprecation applies to all forks, including this `kaazing/node-http2` package.
  Fix: Remove `node-http2` from your project dependencies and refactor your code to use `require('node:http2')` or `import * as http2 from 'node:http2';`.

Install

• npm install node-http2 npm
• yarn add node-http2 yarn
• pnpm add node-http2 pnpm

Imports

• createServer
  wrong:

  const http2 = require('http2'); // This often resolves to the native module

  correct:

  import { createServer } from 'node-http2';

  This package is CommonJS-first; for ES modules, bundlers might be required. Always explicitly refer to 'node-http2' to avoid conflicts with Node.js's built-in 'http2' module.
• get
  wrong:

  import { get } from 'node:http2'; // This is the native module API, not this package

  correct:

  const http2 = require('node-http2');
  http2.get(url, callback);

  The client-side `get` method is part of the package's API. Be careful not to confuse it with the native `node:http2` module which has a different, non-`get` centric client API.
• Http2Server
  wrong:

  import { Http2Server } from 'http2'; // Will likely fail or resolve to native

  correct:

  const { Http2Server } = require('node-http2');

  While not directly exposed as `Http2Server` in the top-level API, internally this package defines server types. Direct import might not be typical for users, but it's important to differentiate from the native `http2.Http2Server`.

Quickstart

Starts an HTTPS/2 server on port 8080 using `node-http2`, serving a 'Hello world' response. Requires self-signed certificates for local testing.

const fs = require('fs');
const http2 = require('node-http2'); // Explicitly import this package

// Ensure you have localhost.key and localhost.crt in an 'example' directory
// For testing, you can generate self-signed certificates:
// openssl genrsa -out example/localhost.key 2048
// openssl req -new -x509 -key example/localhost.key -out example/localhost.crt -days 365 -subj "/CN=localhost"

const options = {
  key: fs.readFileSync('./example/localhost.key'),
  cert: fs.readFileSync('./example/localhost.crt')
};

http2.createServer(options, function(request, response) {
  response.end('Hello world from node-http2!');
}).listen(8080, () => {
  console.log('node-http2 server listening on port 8080 (HTTPS/2)');
  console.log('Try: curl --http2 -k https://localhost:8080/');
});