{"id":11057,"library":"http-server","title":"http-server: A Simple Static HTTP Server","description":"http-server is a robust, zero-configuration command-line HTTP server designed for serving static files efficiently. Currently stable at version `14.1.1`, it has a reasonably active release cadence, addressing security vulnerabilities, adding new features, and dropping older Node.js support. Its key differentiators include ease of use via a simple CLI, support for HTTPS, automatic gzip/brotli compression, CORS headers, basic authentication, and proxying capabilities. It is suitable for local development, testing, and production environments, providing a quick way to serve content without complex setup. The project recently underwent a significant refactor by internalizing the `ecstatic` library's functionality, reducing external dependencies.","status":"active","version":"14.1.1","language":"javascript","source_language":"en","source_url":"git://github.com/http-party/http-server","tags":["javascript","cli","command","static","http","https","http-server","https-server","server"],"install":[{"cmd":"npm install http-server","lang":"bash","label":"npm"},{"cmd":"yarn add http-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For programmatic usage in ESM, the `createServer` function is directly available as a named import. The module itself exports an object.","wrong":"import createServer from 'http-server';","symbol":"createServer (ESM)","correct":"import { createServer } from 'http-server';"},{"note":"The `require('http-server')` call returns an object containing the `createServer` function, among other utilities.","wrong":"const http = require('http-server');\nconst server = http.createServer();","symbol":"createServer (CommonJS)","correct":"const { createServer } = require('http-server');"},{"note":"The primary usage of http-server is via its command-line interface, typically invoked with `npx` or a global installation.","wrong":"node http-server","symbol":"http-server (CLI)","correct":"npx http-server [path] [options]"}],"quickstart":{"code":"const http = require('http-server');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create a temporary public directory and some static files\nconst publicDir = path.join(__dirname, 'public-server-root');\nif (!fs.existsSync(publicDir)) {\n  fs.mkdirSync(publicDir);\n}\nfs.writeFileSync(path.join(publicDir, 'index.html'), '<h1>Hello from http-server programmatically!</h1>');\nfs.writeFileSync(path.join(publicDir, 'data.json'), '{\"message\": \"API data from static file\"}');\n\nconst options = {\n  root: publicDir, // Directory to serve files from\n  port: 8080,\n  host: '0.0.0.0',\n  cache: -1, // Disable caching for development\n  cors: true, // Enable CORS\n  showDir: true, // Show directory listings\n  autoIndex: true, // Display autoIndex\n  ssl: false, // No SSL for this example\n  logFn: (req, res, error) => {\n    // Custom logging for each request\n    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url} - ${res.statusCode}`);\n  }\n};\n\nconst serverInstance = http.createServer(options);\n\nserverInstance.listen(options.port, options.host, () => {\n  console.log(`http-server running on http://${options.host}:${options.port}`);\n  console.log(`Serving files from: ${options.root}`);\n  console.log('Access http://localhost:8080/index.html or http://localhost:8080/data.json');\n});\n\n// To stop the server gracefully, you would call serverInstance.close();","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade http-server to version `14.1.1` or higher immediately.","message":"A critical path traversal vulnerability (CVE-2021-44906) was patched. This could allow attackers to access arbitrary files outside the served directory.","severity":"breaking","affected_versions":"<14.1.1"},{"fix":"Upgrade to `14.1.0` or `13.1.0` (or newer patch versions) to ensure stability and security.","message":"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.","severity":"breaking","affected_versions":"<14.1.0 (for v14.x) and <13.1.0 (for v13.x)"},{"fix":"Upgrade your Node.js runtime to version 12 or higher.","message":"Node.js 10 support was dropped in `v14.0.0` to enable new features like charset sniffing.","severity":"breaking","affected_versions":">=14.0.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.","message":"The `server: http-server-${version}` HTTP header is no longer sent with responses since `v0.13.0`.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Always use the full `http-server` command or explicitly create your own alias.","message":"The automatic `hs` alias for the `http-server` command was removed.","severity":"deprecated","affected_versions":">=13.0.1"},{"fix":"Use the `-c-1` option (e.g., `http-server . -c-1`) to disable caching for development purposes.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use the `-p` flag to specify a different port (e.g., `http-server -p 3000`) or terminate the process using the port.","cause":"The specified port (default 8080) is already in use by another application.","error":"Error: listen EADDRINUSE :::8080"},{"fix":"Add the `--cors` flag when starting http-server (e.g., `http-server . --cors`).","cause":"Your web browser is blocking a cross-origin request because the http-server is not sending the necessary CORS headers.","error":"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."},{"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.","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.","error":"http-server: command not found"},{"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.","cause":"You enabled HTTPS (`--ssl` or `--tls`) but did not provide valid certificate and key files, or the paths are incorrect.","error":"ERR_SSL_PROTOCOL_ERROR (in browser) or SSL_CTX_new:SSL routines::no certificate assigned (in console)"}],"ecosystem":"npm"}