http-serve: Command-line HTTP Server

1.0.1 verified Thu Apr 23 auth: no javascript

http-serve is a command-line HTTP server that builds upon the foundational `http-server` package, enhancing it with key features such as gzip compression and a configurable fallback mechanism for nonexistent routes (404s). It also includes built-in HTTPS support, making it a robust solution for both local development and front-end testing environments. The current stable version is 1.0.1, indicating a mature yet focused tool. As a CLI utility, its release cadence is typically driven by new feature additions, bug fixes, or dependency updates. Its primary differentiators lie in its zero-configuration approach, ease of use for quick static file serving, and the added capabilities for gzipped assets and Single Page Application (SPA) routing compared to basic HTTP servers.

Common errors

error sh: http-serve: command not found ↓

cause `http-serve` is not installed globally or is not accessible in the current shell's PATH, or you are trying to run it directly without `npx` when installed locally.

fix

Install globally: npm i -g http-serve. Or run locally using npx: npx http-serve .. Or add a script to package.json and run with npm run <script-name>.

error Error: listen EADDRINUSE: address already in use :::8080 ↓

cause Another process on your system is already listening on the specified port (8080 by default).

fix

Use a different port number with the -p flag, e.g., http-serve . -p 3000. Alternatively, identify and terminate the process currently using port 8080.

error ERR_SSL_PROTOCOL_ERROR (in browser) or related HTTPS connection issues ↓

cause The `--ssl` flag was used without valid `--cert` and `--key` files, or the provided certificates are invalid, expired, or not trusted by the browser (common with self-signed certificates).

fix

Ensure that cert.pem and key.pem files are valid and correctly specified via --cert and --key. If using self-signed certificates for local development, you may need to manually trust them in your browser's security settings.

error Files are not being served with gzip compression. ↓

cause The `--gzip` flag is enabled, but the corresponding `.gz` versions of the static assets do not exist, or the client (browser) does not include `Accept-Encoding: gzip` in its request headers.

fix

Verify that gzipped versions of your files exist (e.g., app.js.gz for app.js). Use gzip -k to create them without deleting originals. Ensure your browser is configured to accept gzip encoding.

Warnings

gotcha The `--gzip` option only serves pre-gzipped files. It does not compress files on the fly. You must provide `*.js.gz` for `*.js` etc., for it to work. ↓

fix Manually gzip your static assets (e.g., `gzip -k public/app.js` to create `public/app.js.gz`) and ensure the gzipped versions exist alongside the original files.

gotcha The default serving path is `./public` if that directory exists; otherwise, it defaults to the current working directory (`./`). Be explicit with the `[path]` argument to avoid confusion. ↓

fix Always specify the directory you intend to serve, e.g., `http-serve ./dist` or `http-serve .`.

gotcha When using `--ssl`, you must provide paths to a valid SSL certificate (`--cert`) and key (`--key`) file. Using self-signed certificates for local development may trigger browser security warnings. ↓

fix Generate or obtain a valid `cert.pem` and `key.pem` pair and specify their paths: `http-serve . --ssl --cert ./cert.pem --key ./key.pem`. For local development, be prepared to accept browser warnings for self-signed certs.

gotcha `http-serve` is an 'extended version' of `http-server`. While it adds features like gzip and fallback, subtle behavioral differences, different default configurations, or divergence in unmentioned features might exist compared to the original `http-server`. ↓

fix Review the documentation for `http-serve` specifically to understand its unique options and behaviors, especially if migrating from or comparing against `http-server`.

Install

npm install http-serve

yarn add http-serve

pnpm add http-serve

Imports

http-serve
wrong
```
import { serve } from 'http-serve'
```
correct
```
npm i -g http-serve
http-serve . -p 8080
```
This package is primarily a command-line interface (CLI) tool and is not intended for direct programmatic import via `import` or `require`. It is typically installed globally or run via `npx` or `package.json` scripts.
http-serve (via npx)
wrong
```
node_modules/http-serve/bin/http-serve
```
correct
```
npx http-serve . -p 8080 --gzip
```
For project-specific use without global installation, `npx` is the recommended method to execute the CLI directly from `node_modules`.

http-serve (package.json script)

wrong

node http-serve.js

correct

// package.json
{
  "scripts": {
    "serve": "http-serve ./dist -p 8081 --cors --fallback /index.html"
  }
}
// Then run: npm run serve

Integrating `http-serve` into `package.json` scripts allows for consistent project-level command execution and configuration.

Quickstart

Sets up a minimal static site, installs `http-serve` locally, and runs it via an `npm` script on port 8080 with gzip, a 404 fallback, and auto-opens in a browser.

mkdir my-project
cd my-project

# 1. Initialize project and install http-serve
npm init -y
npm i -D http-serve

# 2. Create some static files
mkdir public
echo '<h1>Hello from http-serve!</h1><p>This is your index page.</p>' > public/index.html
echo 'console.log("This is an asset.");' > public/app.js
echo 'alert("404 Not Found!");' > public/404.html

# 3. Add a 'start' script to package.json
#    (replace existing 'test' script or add to 'scripts' object)
npm pkg set scripts.start="http-serve ./public -p 8080 --ext html --gzip --fallback /404.html -o --silent"

# 4. Run the server
npm start

# This command starts an HTTP server on http://localhost:8080,
# serves content from './public', enables gzip (if .gz files exist),
# redirects 404s to /404.html, and opens the browser automatically.