http-server README

The project's README from github.com/http-party/http-server. As one markdown file: README.md.

GitHub Workflow Status (master) npm homebrew npm downloads license

http-server: a simple static HTTP server

http-server is a simple, zero-configuration command-line static HTTP server. It is powerful enough for production usage, but it's simple and hackable enough to be used for testing, local development and learning.

Example of running http-server

Installation:

Running on-demand:

Using npx you can run the script without installing it first:

npx http-server [path] [options]

Globally via npm

npm install --global http-server

This will install http-server globally so that it may be run from the command line anywhere.

Globally via Homebrew

brew install http-server

As a dependency in your npm package:

npm install http-server

Using Docker

Note: a public image is not provided currently, but you can build one yourself with the provided Dockerfile.

  1. Create an image
    docker build -t my-image .
  2. Run a container
    docker run -p 8080:8080 -v "${pwd}:/public" my-image
    In the example above we're serving the directory ./ (working directory). If you wanted to serve ./test you'd replace ${pwd} with ${pwd}/test.

Usage:

 http-server [path] [options]

[path] defaults to ./public if the folder exists, and ./ otherwise.

Now you can visit http://localhost:8080 to view your server

Note: Caching is on by default. Add -c-1 as an option to disable caching.

Available Options:

Command Description Defaults
-p or --port Port to use. Use -p 0 to look for an open port, starting at 8080. It will also read from process.env.PORT. 8080
-a Address to use 0.0.0.0
--base-dir Base path to serve files from /
-d Show directory listings true
-dir-overrides-404 Whether -d should override magic 404.html false
-i Display autoIndex true
-g or --gzip When enabled it will serve ./public/some-file.js.gz in place of ./public/some-file.js when a gzipped version of the file exists and the request accepts gzip encoding. If brotli is also enabled, it will try to serve brotli first. false
-b or --brotli When enabled it will serve ./public/some-file.js.br in place of ./public/some-file.js when a brotli compressed version of the file exists and the request accepts br encoding. If gzip is also enabled, it will try to serve brotli first. false
-e or --ext Default file extension if none supplied html
-s or --silent Suppress log messages from output
--coop Enable COOP via the Cross-Origin-Opener-Policy header
--cors Enable CORS via the Access-Control-Allow-Origin header
--private-network-access Enable Private Network Access via the Access-Control-Allow-Private-Network header
--cors Enable CORS via the Access-Control-Allow-Origin: * header. Optionally provide comma-separated values to add to Access-Control-Allow-Headers
-H or --header Add an extra response header (can be used several times)
-o [path] Open browser window after starting the server. Optionally provide a URL path to open. e.g.: -o /other/dir/
-c Set cache time (in seconds) for cache-control max-age header, e.g. -c10 for 10 seconds. To disable caching, use -c-1. 3600
-t Connection timeout in seconds, e.g. -t60 for 1 minute. To disable timeout, use -t0. 120
-T or --title Custom title suffix for the terminal window. The title will be "http-server PORT [TITLE]".
-U or --utc Use UTC time format in log messages.
--log-ip Enable logging of the client's IP address false
-P or --proxy Proxies all requests which can't be resolved locally to the given url. e.g.: -P http://someurl.com
--proxy-options Pass proxy options using nested dotted objects. e.g.: --proxy-options.secure false
--proxy-config Pass in .json configuration file or stringified JSON. e.g.: ./path/to/config.json
--proxy-all Forward every request to the proxy target instead of serving local files false
--proxy-options Pass proxy options using nested dotted objects. e.g.: --proxy-options.secure false
--user or --username Username for basic authentication
--password Password for basic authentication
-S, --tls or --ssl Enable secure request serving with TLS/SSL (HTTPS) false
-C or --cert Path to ssl cert file cert.pem
-K or --key Path to ssl key file key.pem
-r or --robots Automatically provide a /robots.txt (The content of which defaults to User-agent: *\nDisallow: /) false
--no-dotfiles Do not show dotfiles
--mimetypes Path to a .types file for custom mimetype definition
--hide-permissions Do not show file permissions
--allowed-hosts Comma-separated list of hosts allowed to access the server. e.g.: --allowed-hosts localhost,example.com
-h or --help Print this list and exit.
-v or --version Print the version and exit.
--no-panic Don't print error stack in the console, put it in a log file false

Magic Files

Catch-all redirect

To implement a catch-all redirect, use the index page itself as the proxy with:

http-server --proxy http://localhost:8080?

Note the ? at the end of the proxy URL. Thanks to @houston3 for this clever hack!

TLS/SSL

First, you need to make sure that openssl is installed correctly, and you have key.pem and cert.pem files. You can generate them using this command:

openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem

You will be prompted with a few questions after entering the command. Use 127.0.0.1 as value for Common name if you want to be able to install the certificate in your OS's root certificate store or browser so that it is trusted.

This generates a cert-key pair and it will be valid for 3650 days (about 10 years).

Then you need to run the server with -S for enabling SSL and -C for your certificate file.

http-server -S -C cert.pem

If you wish to use a passphrase with your private key you can include one in the openssl command via the -passout parameter (using password of foobar)

e.g. openssl req -newkey rsa:2048 -passout pass:foobar -keyout key.pem -x509 -days 365 -out cert.pem

For security reasons, the passphrase will only be read from the NODE_HTTP_SERVER_SSL_PASSPHRASE environment variable.

This is what should be output if successful:

Starting up http-server, serving ./ through https

http-server settings:
COOP: disabled
CORS: disabled
Cache: 3600 seconds
Connection Timeout: 120 seconds
Directory Listings: visible
AutoIndex: visible
Serve GZIP Files: false
Serve Brotli Files: false
Default File Extension: none

Available on:
  https://127.0.0.1:8080
  https://192.168.1.101:8080
  https://192.168.1.104:8080
Hit CTRL-C to stop the server

Development

Checkout this repository locally, then:

$ npm i
$ npm start

Now you can visit http://localhost:8080 to view your server

You should see the turtle image in the screenshot above hosted at that URL. See the ./public folder for demo content.

http-server (http-party/http-server)

Searching Database…

14.2K ·GitHub
Http-server
What is this?http-server is a simple, zero-configuration command-line static HTTP server: point it at a folder and it serves the files over HTTP. The README says it is powerful enough for production usage, yet simple and hackable enough to be used for testing, local development and learning.
Is it a command-line tool or a library?Both. Its main face is a CLI — run http-server [path] [options] in any folder — but you can also install it as a dependency in your own npm package and use it from your code.
How do I get it running?For a one-off, run npx http-server [path] [options] with no install step at all. To keep it around: npm install --global http-server, or brew install http-server on macOS, then run http-server in the folder you want to serve.
What do I need to have installed beforehand?Just a Node.js runtime and npm — the package targets Node >=16.20.2. On macOS you can skip npm entirely and use Homebrew instead. No databases or other services are required.
Why do I keep seeing stale files when I refresh?Caching is on by default with a cache-control max-age of 3600 seconds. While developing, add -c-1 to disable caching so every request picks up your latest changes.
Does it work on Windows and macOS, or just Linux?It runs anywhere Node runs — Windows, macOS and Linux — since it is a plain Node.js CLI with no OS-specific requirements in the README. A Dockerfile is included for building your own image, as no public Docker image is published.
Can I use it to serve a real site over HTTPS?Yes — the README calls it powerful enough for production usage. Start it with -S (or --tls/--ssl) plus -C cert.pem and -K key.pem for HTTPS, and it also offers basic authentication via --username/--password, CORS via --cors, and custom response headers.
What magic files does it support?index.html is served as the default file for directory requests, and a custom 404.html is served when a file is not found — which the README suggests using for Single-Page App hosting to serve the entry page.
Can it act as a proxy to a backend?Yes: -P or --proxy sends requests that cannot be resolved locally to the given URL, and --proxy-all forwards every request to the proxy target instead of serving local files.
Does it compress responses?Only precompressed files: with -g or --gzip it serves a .gz version in place of the original when one exists on disk and the request accepts gzip, and -b or --brotli does the same for .br files, preferring brotli when both are enabled.
What do I get out of the box with no options?It listens on port 8080, shows directory listings and auto-index, sets cache-control to one hour, and serves index.html as the default document; every default can be overridden with flags such as -p, -d or -c.
What are similar projects?hotel, dufs, qrcp, caddy, truffle, readme-md-generator, portless, nodemon
Which topics is it in?localhost, zero-configuration, encoding, local, npx, hosting, static, development, dockerfile, http-server, https, web-server
Creator
http-party
Size
2.2 MB
Stars
14.2K
Updated
CommitMar 14Releasev14.1.1May 31
Age
15y
Commits · 90 Days