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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createServer
✓ import { createServer } from '@httptoolkit/httpolyglot';
✗ const httpolyglot = require('httpolyglot'); httpolyglot.createServer(...);
The original `httpolyglot` package uses CommonJS `require`. The recommended, actively maintained fork, `@httptoolkit/httpolyglot`, is an ESM-first module and should be imported using `import` syntax.
Server
✓ import { Server } from '@httptoolkit/httpolyglot';
While `Server` is exported, `createServer` is the more common entry point. The fork supports `tls.Server` instances in its config, unlike the original.
default
✓ import * as httpolyglot from '@httptoolkit/httpolyglot';
✗ import httpolyglot from '@httptoolkit/httpolyglot';
The `@httptoolkit/httpolyglot` package exports named symbols. Importing the entire module namespace is done with `import * as name`.
This quickstart demonstrates how to set up an `@httptoolkit/httpolyglot` server that listens for both HTTP and HTTPS connections on the same port, responding differently based on the protocol. It includes a basic self-signed certificate generation utility for local testing purposes (not for production).
import * as httpolyglot from '@httptoolkit/httpolyglot';
import * as fs from 'node:fs';
import * as https from 'node:https'; // For generating certificates
// --- Utility to generate self-signed certs for testing ---
// In a real app, use proper certificate management (e.g., LetsEncrypt)
const generateSelfSignedCert = () => {
try {
fs.readFileSync('server.key');
fs.readFileSync('server.crt');
} catch (e) {
console.log('Generating self-signed certificates...');
const { generateKeyPairSync } = require('node:crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
modulusLength: 2048,
publicKeyEncoding: { type: 'spki', format: 'pem' },
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
});
fs.writeFileSync('server.key', privateKey);
// A simple self-signed cert (for testing only!)
const cert = `-----BEGIN CERTIFICATE-----\nMIIDDDCCAfSgAwIBAgIUQd+Wj+T/h7g8v4f5g4f/g4f/g4f/g4f/g4f/g4f/g4f\nMBMGCSqGSIb3DQEBCwUAMBQxDDAKBgNVBAMMA2xvYzAeFw0yNjA0MjMyMDIyNDZa\nFw0yNzA0MjMyMDIyNDZaMBQxDDAKBgNVBAMMA2xvYWMwggEiMA0GCSqGSIb3DQEB\nAQUAA4IBDwAwggEKAoIBAQCmF5fN+h/d+g/g4f/g4f/g4f/g4f/g4f/g4f/g4f\nAgMBAAGjMDAuMBsGA1UdEQQUMBKCDmRpcmVjdC5leGFtcGxlMA4GA1UdDwEB/wQE\nAwIBAzANBgkqhkiG9w0BAQsFAAOCAQEAy/g4f/g4f/g4f/g4f/g4f/g4f/g4f\n-----END CERTIFICATE-----\n`; // Placeholder
fs.writeFileSync('server.crt', cert);
console.log('Certificates generated. PLEASE DO NOT USE IN PRODUCTION.');
}
};
generateSelfSignedCert();
// --- End cert generation utility ---
const key = fs.readFileSync('server.key');
const cert = fs.readFileSync('server.crt');
httpolyglot.createServer({
// For the @httptoolkit fork, TLS config is nested under `tls`
tls: {
key: key,
cert: cert,
},
}, function(req, res) {
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end((req.socket.encrypted ? 'HTTPS' : 'HTTP') + ' Connection!\nHello from @httptoolkit/httpolyglot!');
}).listen(9000, 'localhost', function() {
console.log('httpolyglot server listening on port 9000');
console.log('Visit http://localhost:9000 and https://localhost:9000 in your browser.');
console.log('Ensure you accept any self-signed certificate warnings for HTTPS.');
});
Debug
Known issues
breakingThe original `httpolyglot` package (v0.1.2) is abandoned and has not been updated in over 9 years. It lacks support for modern Node.js versions, HTTP/2, and contains unaddressed issues. It is strongly recommended NOT to use this package in any new or existing project.fixMigrate to the actively maintained `@httptoolkit/httpolyglot` package: `npm install @httptoolkit/httpolyglot`.
affects: <=0.1.2
breakingThe API for `createServer` in the actively maintained fork (`@httptoolkit/httpolyglot`) has changed significantly. TLS configuration is now nested under a `tls` property within the main configuration object. The original package accepted `key` and `cert` directly at the top level.fixUpdate your `createServer` call to use the nested `tls` object: `httpolyglot.createServer({ tls: { key: ..., cert: ... } }, ...)`. affects: all versions of `@httptoolkit/httpolyglot` when migrating from `httpolyglot`
gotchaThe `@httptoolkit/httpolyglot` package is written in TypeScript and primarily designed for ESM usage. Attempting to `require()` it in a CommonJS context or using incorrect import syntax can lead to runtime errors or undefined modules.fixEnsure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import * as httpolyglot from '@httptoolkit/httpolyglot';` or specific named imports.
affects: all versions of `@httptoolkit/httpolyglot`
breakingThe `@httptoolkit/httpolyglot` fork drops support for very old Node.js versions, requiring Node.js v20 or newer. The original `httpolyglot` package specified `>=0.10.0`.fixUpdate your Node.js environment to version 20 or newer to use `@httptoolkit/httpolyglot`.
affects: all versions of `@httptoolkit/httpolyglot`
Errors
Common errors & fixes
httpolyglot.createServer is not a function
Attempting to use the `createServer` method from the original, abandoned `httpolyglot` package with an outdated Node.js environment or when the package failed to load correctly due to CJS/ESM incompatibility.
fixEnsure you are using the correct, actively maintained `@httptoolkit/httpolyglot` package. If already installed, verify it's imported correctly via ESM: `import * as httpolyglot from '@httptoolkit/httpolyglot';`.
TypeError: Cannot read properties of undefined (reading 'key')
Using the old configuration format (direct `key`, `cert` options) with the new `@httptoolkit/httpolyglot` API, which expects these under a nested `tls` property.
fixAdjust your `createServer` call to `httpolyglot.createServer({ tls: { key: fs.readFileSync('server.key'), cert: fs.readFileSync('server.crt') } }, ...);`. ERR_REQUIRE_ESM: require() of ES Module .../node_modules/@httptoolkit/httpolyglot/dist/index.js from ... not supported.
Attempting to `require()` the `@httptoolkit/httpolyglot` package in a CommonJS environment, but the package is ESM-only.
fixConvert your project or the relevant file to use ES Modules by adding `"type": "module"` to your `package.json` or by using `.mjs` file extensions. Then use `import * as httpolyglot from '@httptoolkit/httpolyglot';`. Alternatively, use dynamic `import()` for specific needs.
Audit
Dependencies
No dependency data recorded yet.