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.
http
✓ const http = require('http-server');
✗ import http from 'http-server';
Main entry point for programmatic usage. The package is CommonJS-first, so `require` is the standard import method.
createServer
✓ const { createServer } = require('http-server');
✗ import { createServer } from 'http-server';
Function to programmatically create an HTTP server instance. This module is CommonJS-first.
HttpServerOptions
✓ import type { HttpServerOptions } from 'http-server';
✗ import { HttpServerOptions } from 'http-server';
Type definition for server configuration options, available when using TypeScript. Importing types with `import type` is recommended to avoid bundling issues.
Demonstrates global installation and basic CLI usage, alongside a programmatic setup serving static files with custom options, including CORS and caching control.
// Install http-server globally
// npm install -g http-server
// Navigate to your project directory
// cd my-static-app
// Start the server, serving the current directory
// Opens a browser window by default on http://localhost:8080
http-server -o
// Alternatively, specify a port, disable caching, and enable CORS
// http-server . -p 3000 --cors -c-1
// Programmatic example (save as server.js and run `node server.js`)
const { createServer } = require('http-server');
const path = require('path');
const server = createServer({
root: path.join(__dirname, 'public'), // Serve files from a 'public' subdirectory
cache: -1, // Disable caching for development
cors: true, // Enable CORS
showDir: true, // Show directory listings
autoIndex: true, // Display autoIndex
headers: { // Custom headers can be useful, e.g., for security or features
'X-Custom-Header': 'Hello from http-server'
}
});
server.listen(8080, '0.0.0.0', () => {
console.log('HTTP Server listening on http://0.0.0.0:8080');
console.log('Serving directory:', path.join(__dirname, 'public'));
});
http-server --version
Debug
Known issues
breakingNode.js 10 support was dropped in `v14.0.0`. Users on older Node.js versions will need to upgrade Node.js or remain on an older `http-server` version.fixUpgrade Node.js to a supported version (Node.js 12+ recommended) or pin `http-server` to `<14.0.0`.
affects: >=14.0.0
breakingThe `colors.js` dependency was replaced with `chalk` in `v14.1.0` (and backported to `v13.1.0`) due to a critical supply chain security vulnerability found in `colors.js`. Direct or indirect reliance on `colors.js` through `http-server` prior to these versions could expose applications to risks.fixUpgrade `http-server` to `v14.1.0` or higher, or `v13.1.0` or higher. Review your dependency tree for other packages that might still depend on compromised `colors.js` versions.
affects: <14.1.0 and <13.1.0
breakingThe `server: http-server-${version}` header is no longer sent with responses since `v0.13.0` (which predates the semantic versioning scheme starting at `v13.0.0`). This might affect systems that rely on this header for server identification.fixAdjust any client-side or proxy configurations that depend on the presence or specific format of the `Server` header.
affects: >=0.13.0 (effectively >=13.0.0)
deprecatedThe automatic `hs` alias for the `http-server` command was removed in `v13.0.1`. Users accustomed to using `hs` will need to switch to `http-server`.fixUse the full `http-server` command instead of the `hs` alias.
affects: >=13.0.1
gotchaBy default, `http-server` serves `./public` if that directory exists; otherwise, it serves the current working directory (`./`). This default behavior can be a common source of confusion if a `public` directory is unintentionally present or missing.fixAlways explicitly specify the path to serve, e.g., `http-server .` to serve the current directory, or `http-server ./dist` for a build output directory.
affects: >=0.1.0
gotchaBy default, `http-server` sets a `Cache-Control` header with `max-age=3600` (1 hour). While good for production, this can lead to stale content during local development. To disable caching, the `-c-1` option must be used.fixFor development, always use `http-server -c-1` to disable caching.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Cannot find module 'http-server'
The `http-server` package is not installed globally or locally within your project.
fixInstall globally: `npm install -g http-server`. Or install locally: `npm install http-server` and run via `npx http-server` or a `package.json` script.
Error: listen EADDRINUSE: address already in use 0.0.0.0:8080
Another process is already using the specified port (8080 by default).
fixTerminate the process using the port, or start `http-server` on a different port using the `-p` option, e.g., `http-server -p 3000`.
ENOENT: no such file or directory, stat '/path/to/nonexistent/directory/index.html'
The specified path for the server (or the default path) does not exist or does not contain a default `index.html` (when autoIndex is false).
fixEnsure the directory exists and contains the necessary files, or explicitly provide a valid path, e.g., `http-server .`.
Audit
Dependencies
No dependency data recorded yet.