http-serve

library0.246jsnpmunverified

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.

http-networking devops web-framework

npm install http-serve

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-SERVE

http-serve

http-networkingjavascriptv0.246

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

http-serve

✓ npm i -g http-serve http-serve . -p 8080

✗ import { serve } from 'http-serve'

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)

✓ npx http-serve . -p 8080 --gzip

✗ node_modules/http-serve/bin/http-serve

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)

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

✗ node http-serve.js

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

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.

http-serve --version

Debug

Known issues

gotchaThe `--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.

affects: >=1.0.0

gotchaThe 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 .`.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

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`.

affects: >=1.0.0

Errors

Common errors & fixes

sh: http-serve: command not found

`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: listen EADDRINUSE: address already in use :::8080

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.

ERR_SSL_PROTOCOL_ERROR (in browser) or related HTTPS connection issues

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.

Files are not being served with gzip compression.

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.

Upgrade

Version history

0.246latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/dkarmalita/http-serve ↗

packagehttps://www.npmjs.com/package/http-serve ↗