http-server: A Simple Static HTTP Server

Common errors

• Error: listen EADDRINUSE :::8080

  cause The specified port (default 8080) is already in use by another application.
  fix Use 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.

  cause Your web browser is blocking a cross-origin request because the http-server is not sending the necessary CORS headers.
  fix Add the `--cors` flag when starting http-server (e.g., `http-server . --cors`).

• http-server: command not found

  cause The `http-server` command is not recognized by your shell, likely because it's not installed globally or `npx` is not in your PATH.
  fix Install 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)

  cause You enabled HTTPS (`--ssl` or `--tls`) but did not provide valid certificate and key files, or the paths are incorrect.
  fix Provide 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.

Warnings

• breaking A critical path traversal vulnerability (CVE-2021-44906) was patched. This could allow attackers to access arbitrary files outside the served directory.
  Fix: Upgrade http-server to version `14.1.1` or higher immediately.
• breaking Due 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.
  Fix: Upgrade to `14.1.0` or `13.1.0` (or newer patch versions) to ensure stability and security.
• breaking Node.js 10 support was dropped in `v14.0.0` to enable new features like charset sniffing.
  Fix: Upgrade your Node.js runtime to version 12 or higher.
• breaking The `server: http-server-${version}` HTTP header is no longer sent with responses since `v0.13.0`.
  Fix: If your application explicitly relied on this header, you will need to adjust your logic or implement a custom solution to add it back.
• deprecated The automatic `hs` alias for the `http-server` command was removed.
  Fix: Always use the full `http-server` command or explicitly create your own alias.
• gotcha Caching is enabled by default with a `max-age` of 3600 seconds. This can lead to unexpected behavior during development when files are frequently changed.
  Fix: Use the `-c-1` option (e.g., `http-server . -c-1`) to disable caching for development purposes.

Install

• npm install http-server npm
• yarn add http-server yarn
• pnpm add http-server pnpm

Imports

• createServer (ESM)
  wrong:

  import createServer from 'http-server';

  correct:

  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)
  wrong:

  const http = require('http-server');
  const server = http.createServer();

  correct:

  const { createServer } = require('http-server');

  The `require('http-server')` call returns an object containing the `createServer` function, among other utilities.
• http-server (CLI)
  wrong:

  node http-server

  correct:

  npx http-server [path] [options]

  The primary usage of http-server is via its command-line interface, typically invoked with `npx` or a global installation.

Quickstart

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();