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 (ESM)
✓ import { createServer } from 'http-server';
✗ import createServer from 'http-server';
For programmatic usage in ESM, the `createServer` function is directly available as a named import. The module itself exports an object.
createServer (CommonJS)
✓ const { createServer } = require('http-server');
✗ const http = require('http-server');
const server = http.createServer();
The `require('http-server')` call returns an object containing the `createServer` function, among other utilities.
http-server (CLI)
✓ npx http-server [path] [options]
✗ node http-server
The primary usage of http-server is via its command-line interface, typically invoked with `npx` or a global installation.
This quickstart demonstrates how to programmatically start an http-server instance, configure it with common options like CORS, port, and root directory, and serve static content. It also includes basic custom logging.
const http = require('http-server');
const path = require('path');
const fs = require('fs');
// Create a temporary public directory and some static files
const publicDir = path.join(__dirname, 'public-server-root');
if (!fs.existsSync(publicDir)) {
fs.mkdirSync(publicDir);
}
fs.writeFileSync(path.join(publicDir, 'index.html'), '<h1>Hello from http-server programmatically!</h1>');
fs.writeFileSync(path.join(publicDir, 'data.json'), '{"message": "API data from static file"}');
const options = {
root: publicDir, // Directory to serve files from
port: 8080,
host: '0.0.0.0',
cache: -1, // Disable caching for development
cors: true, // Enable CORS
showDir: true, // Show directory listings
autoIndex: true, // Display autoIndex
ssl: false, // No SSL for this example
logFn: (req, res, error) => {
// Custom logging for each request
console.log(`[${new Date().toISOString()}] ${req.method} ${req.url} - ${res.statusCode}`);
}
};
const serverInstance = http.createServer(options);
serverInstance.listen(options.port, options.host, () => {
console.log(`http-server running on http://${options.host}:${options.port}`);
console.log(`Serving files from: ${options.root}`);
console.log('Access http://localhost:8080/index.html or http://localhost:8080/data.json');
});
// To stop the server gracefully, you would call serverInstance.close();
http-server --version
Debug
Known issues
breakingA critical path traversal vulnerability (CVE-2021-44906) was patched. This could allow attackers to access arbitrary files outside the served directory.fixUpgrade http-server to version `14.1.1` or higher immediately.
affects: <14.1.1
breakingDue to a supply chain issue/protest with the `colors.js` package, http-server urgently replaced it with `chalk` in versions `14.1.0` and `13.1.0`. This was an emergency fix addressing potential instability.fixUpgrade to `14.1.0` or `13.1.0` (or newer patch versions) to ensure stability and security.
affects: <14.1.0 (for v14.x) and <13.1.0 (for v13.x)
breakingNode.js 10 support was dropped in `v14.0.0` to enable new features like charset sniffing.fixUpgrade your Node.js runtime to version 12 or higher.
affects: >=14.0.0
breakingThe `server: http-server-${version}` HTTP header is no longer sent with responses since `v0.13.0`.fixIf your application explicitly relied on this header, you will need to adjust your logic or implement a custom solution to add it back.
affects: >=0.13.0
deprecatedThe automatic `hs` alias for the `http-server` command was removed.fixAlways use the full `http-server` command or explicitly create your own alias.
affects: >=13.0.1
gotchaCaching is enabled by default with a `max-age` of 3600 seconds. This can lead to unexpected behavior during development when files are frequently changed.fixUse the `-c-1` option (e.g., `http-server . -c-1`) to disable caching for development purposes.
affects: All
Errors
Common errors & fixes
Error: listen EADDRINUSE :::8080
The specified port (default 8080) is already in use by another application.
fixUse the `-p` flag to specify a different port (e.g., `http-server -p 3000`) or terminate the process using the port.
Access to XMLHttpRequest at 'http://localhost:8080/data.json' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Your web browser is blocking a cross-origin request because the http-server is not sending the necessary CORS headers.
fixAdd the `--cors` flag when starting http-server (e.g., `http-server . --cors`).
http-server: command not found
The `http-server` command is not recognized by your shell, likely because it's not installed globally or `npx` is not in your PATH.
fixInstall it globally via npm (`npm install -g http-server`) or use `npx` to run it without global installation (`npx http-server`). Ensure your PATH includes `npm`'s global bin directory if installed globally.
ERR_SSL_PROTOCOL_ERROR (in browser) or SSL_CTX_new:SSL routines::no certificate assigned (in console)
You enabled HTTPS (`--ssl` or `--tls`) but did not provide valid certificate and key files, or the paths are incorrect.
fixProvide valid certificate and key files using `--cert path/to/cert.pem --key path/to/key.pem`. You can generate self-signed certificates for local development.
Audit
Dependencies
No dependency data recorded yet.