Supercharge Your Local Web Development with http-server: A Simple Static Server

Http-server stands out as an incredibly user-friendly, zero-configuration command-line tool designed to serve static HTTP servers. Its strength lies in its simplicity and adaptability, making it equally suitable for robust production environments and lightweight tasks like testing, local development, and educational purposes.

Example of http-server in action, showcasing its straightforward execution and directory listing capabilities.

Installation: Multiple Ways to Get Started

There are several convenient methods to install and run http-server, catering to different preferences and environments:

Run On-Demand with npx

For users who prefer not to install tools globally, npx (Node Package eXecutor) offers a seamless way to run http-server directly:

npx http-server [path] [options]

This command fetches and executes http-server without requiring a prior global installation.

Global Installation via npm

The most common method is to install http-server globally using npm (Node Package Manager), which is included with Node.js:

npm install --global http-server

After this command, http-server becomes accessible from your command line, regardless of your current directory.

Installation via Homebrew (macOS)

macOS users can leverage Homebrew, a popular package manager, for installation:

brew install http-server

This integrates http-server into your system via Homebrew’s package management system.

Incorporate as an npm Package Dependency

If you intend to use http-server as part of your project’s development workflow, you can install it as a project dependency:

npm install http-server

This adds http-server to your project’s node_modules directory and package.json file.

Project badges indicating build status, npm version, Homebrew availability, npm downloads, and license for the http-server project.

Basic Usage: Launching Your Server

To start serving files, navigate to your project directory in the command line and run:

http-server [path] [options]

The [path] argument specifies the directory to be served. If omitted, http-server defaults to ./public if it exists, otherwise it serves the current directory ./.

Once launched, you can access your server in a web browser at http://localhost:8080.

Important Note: http-server enables caching by default for improved performance. To disable caching, use the -c-1 option.

Configuration Options: Tailoring http-server to Your Needs

http-server offers a range of command-line options to customize its behavior:

Command	Description	Defaults
-p or --port	Specify the port number. Use -p 0 to automatically find an available port starting from 8080. It also respects the process.env.PORT environment variable.	8080
-a	Define the address to bind to.	0.0.0.0 (all interfaces)
-d	Enable or disable directory listings.	true (enabled)
-i	Toggle autoIndex page display for directory listings.	true (enabled)
-g or --gzip	Serve pre-compressed .js.gz files when available and the client accepts gzip encoding. Brotli compression takes precedence if also enabled.	false (disabled)
-b or --brotli	Serve pre-compressed .js.br files when available and the client accepts brotli encoding. Brotli is prioritized over gzip if both are enabled.	false (disabled)
-e or --ext	Set the default file extension when none is provided in the URL.	html
-s or --silent	Suppress server log messages in the output.
--cors	Enable Cross-Origin Resource Sharing (CORS) by setting the Access-Control-Allow-Origin header to *.
-o [path]	Automatically open a browser window after server start. Optionally specify a URL path to open. Example: -o /docs/index.html.
-c	Control cache duration (in seconds) for the cache-control max-age header. For instance, -c10 sets a 10-second cache. Use -c-1 to completely disable caching.	3600 (1 hour)
-U or --utc	Display log timestamps in UTC format.
--log-ip	Enable logging of client IP addresses in server logs.	false (disabled)
-P or --proxy	Configure a proxy server for requests that cannot be resolved locally. Example: -P http://api.example.com.
--proxy-options	Pass advanced proxy options using nested dotted objects, based on node-http-proxy options. Example: --proxy-options.secure false.
--username	Set a username for basic HTTP authentication.
--password	Set a password for basic HTTP authentication.
-S, --tls or --ssl	Enable HTTPS (TLS/SSL) secure serving.	false (disabled)
-C or --cert	Specify the path to your SSL certificate file.	cert.pem
-K or --key	Specify the path to your SSL key file.	key.pem
-r or --robots	Automatically serve a /robots.txt file. Default content is User-agent: *nDisallow: /.	false (disabled)
--no-dotfiles	Prevent serving dotfiles (files starting with .).
--mimetypes	Provide a path to a .types file for custom MIME type definitions.
-h or --help	Show the help documentation and exit.
-v or --version	Print the http-server version and exit.

Magic Files: Enhancing Single-Page Applications and Custom Error Pages

http-server recognizes special filenames to enhance functionality:

• index.html: When a directory is requested, http-server will automatically serve index.html if present, making it ideal for single-page application routing.
• 404.html: If a requested file is not found, http-server will serve 404.html if it exists in the served directory, allowing for custom 404 error pages and SPA routing.

Implementing Catch-All Redirects for SPAs

For single-page applications that rely on client-side routing, you can implement a catch-all redirect using http-server‘s proxy feature:

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

The ? at the end of the proxy URL is crucial; it instructs http-server to proxy all unresolved requests to the index page, enabling client-side routing to handle them.

Securing Your Server with TLS/SSL (HTTPS)

To enable HTTPS for local development or secure testing, http-server supports TLS/SSL.

First, ensure you have openssl installed. Then, generate self-signed certificates using this command:

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

When prompted for “Common Name,” use 127.0.0.1 if you intend to trust the certificate in your local browser or OS certificate store.

This generates key.pem (private key) and cert.pem (certificate) files valid for approximately 10 years.

To launch http-server with SSL, use the -S flag and specify the certificate file path with -C:

http-server -S -C cert.pem

For enhanced security with a passphrase-protected private key, include the -passout parameter in your openssl command:

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

Set the NODE_HTTP_SERVER_SSL_PASSPHRASE environment variable to your passphrase for http-server to access it securely.

Upon successful SSL setup, the output will indicate HTTPS serving and provide HTTPS URLs for access.

Starting up http-server, serving ./ through https
http-server settings:
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 Setup for http-server

To contribute to http-server or run a development version:

1. Clone the repository locally.
2. Install dependencies: npm install
3. Start the server: npm start

This launches http-server serving the ./public directory, which includes demo content like the turtle image showcased in the initial screenshot. You can access it at http://localhost:8080.