HTTP/2 Support for Express

Common errors

• ERR_HTTP2_INCOMPATIBLE_SERVER

  cause An HTTP/1.1 client attempted to connect to an HTTP/2 server configured with `allowHTTP1: false`.
  fix Configure the HTTP/2 server with `allowHTTP1: true` in the options object if HTTP/1.1 client compatibility is desired. Otherwise, ensure all connecting clients support HTTP/2.

• Error: EISDIR: illegal operation on a directory, read

  cause The `fs.readFileSync` calls for `key` or `cert` were provided with paths to directories instead of the actual certificate and key files.
  fix Verify that `options.key` and `options.cert` point to the full file paths of your TLS certificate key and certificate files, respectively, not just their containing directories.

• TypeError: res.push is not a function

  cause Attempting to use `res.push()` for Server Push, a feature removed in `http2-express`.
  fix Remove all calls to `res.push()` and refactor the application to use alternative methods for asset delivery, such as Link preload headers, as HTTP/2 Server Push is no longer supported by this package or widely by browsers.

Warnings

• breaking This package explicitly removes support for HTTP/2 Server Push, which was present in its predecessor `http2-express-bridge`. Most major browsers and HTTP/2 clients have deprecated or disabled Server Push due to limited performance gains.
  Fix: Review and remove any application logic that relies on HTTP/2 Server Push. Re-evaluate asset delivery strategies using standard HTTP/2 features or preloading via Link headers.
• gotcha The package's `package.json` specifies Node.js version `>= 20.0.0` in its 'engines' field, while the README recommends `>= 19`. Running on Node.js versions older than 20.0.0 may lead to unexpected behavior or missing features.
  Fix: Ensure your Node.js environment is version 20.0.0 or higher for full compatibility and stability.
• gotcha Setting `allowHTTP1: false` in the `http2.createSecureServer` options will prevent HTTP/1.1 clients from connecting to your server, resulting in connection errors for older browsers or clients that do not support HTTP/2.
  Fix: If backward compatibility with HTTP/1.1 clients is required, set `allowHTTP1: true` in the server options. This allows the server to negotiate between HTTP/1.1 and HTTP/2 protocols.
• gotcha While `http2-express` is designed as a drop-in replacement for `http2-express-bridge`, applications relying on specific internal behaviors or undocumented features of the old bridge might encounter subtle issues beyond the removal of Server Push.
  Fix: Perform thorough regression testing after migrating from `http2-express-bridge` to ensure all functionalities behave as expected, especially if your application had complex HTTP/2 interactions.
• gotcha Version 1.0.0 of `http2-express` had an issue with h2c (running HTTP/2 without TLS). While fixed in 1.0.1, users on the initial release might encounter problems when creating non-HTTPS HTTP/2 servers.
  Fix: Upgrade to `http2-express@^1.0.1` or a newer version to ensure proper functionality for h2c (non-HTTPS HTTP/2) servers.

Install

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

Imports

• http2Express
  wrong:

  import { http2Express } from 'http2-express';

  correct:

  import http2Express from 'http2-express';

  The package exports a single function as its default, which is used to wrap an Express application instance. CommonJS `const http2Express = require('http2-express');` also works.
• express
  wrong:

  const express = require('express');

  correct:

  import express from 'express';

  Express is a peer dependency and must be imported separately. The `http2-express` function then takes the Express app instance. The wrong example refers to CommonJS usage in an ESM context without proper loader configuration.
• http2
  wrong:

  import http2 from 'node:http2';

  correct:

  import * as http2 from 'node:http2';

  The native Node.js HTTP/2 module is essential for creating the server and is typically imported as a namespace object (`* as`). Using `node:` prefix is best practice for built-in modules in modern Node.js ESM.

Quickstart

This example demonstrates setting up a basic HTTP/2 Express server with TLS (HTTPS/2) support, serving a 'Hello World' message. It highlights how to wrap an Express app, configure certificates, and listen for connections.

import express from 'express';
import * as http2 from 'node:http2';
import http2Express from 'http2-express';
import fs from 'node:fs';

const app = http2Express(express);

app.get('/', (req, res) => {
  res.send('Hello World from HTTP/2!');
});

const options = {
  key: fs.readFileSync(process.env.HTTP2_KEY_PATH ?? 'path/to/your/certificate.key'),
  cert: fs.readFileSync(process.env.HTTP2_CERT_PATH ?? 'path/to/your/certificate.crt'),
  passphrase: process.env.HTTP2_CERT_PASSPHRASE ?? 'your_certificate_passphrase',
  allowHTTP1: false
};

const server = http2.createSecureServer(options, app);

server.listen(44320, () => {
  console.info('HTTP/2 server listening on https://localhost:44320...');
});