Simple Node HTTP Server for Static File Serving

http-server stands out as a remarkably simple yet powerful command-line static HTTP server built on Node.js. Designed with zero-configuration in mind, it’s the perfect tool for a wide range of scenarios, from quickly serving static files for local development and testing to even handling production workloads. Its ease of use and hackable nature make it an invaluable asset for developers at all levels.

Demonstration of using the Node.js http-server to serve static files from a public directory.

Installation Guide for Node HTTP Server

There are several convenient methods to get http-server up and running on your system, catering to different needs and preferences.

Quick On-Demand Execution with npx

For users who prefer not to install packages globally, npx (Node Package eXecutor) provides a seamless way to run http-server on demand:

npx http-server [path] [options]

This command fetches and executes http-server without requiring a prior global installation, making it ideal for quick, one-off server instances.

Global Installation via npm

To make http-server accessible from any command line location, you can install it globally using npm (Node Package Manager):

npm install --global http-server

After this global installation, the http-server command becomes available system-wide.

Installation via Homebrew on macOS

macOS users can leverage Homebrew, a popular package manager, to install http-server:

brew install http-server

This method integrates http-server smoothly into the macOS environment.

Adding as a Project Dependency

If you intend to incorporate http-server into your Node.js project, 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.

Basic Usage of Node HTTP Server

Once installed, starting http-server is straightforward. In its simplest form, navigate to your project directory in the terminal and run:

http-server

By default, http-server serves files from the ./public directory if it exists. Otherwise, it defaults to serving the current directory (./). You can also specify a different directory to serve:

http-server path/to/your/directory

After execution, http-server will provide a local URL, typically http://localhost:8080, to access your served files in a web browser.

Important Note: Caching is enabled by default to enhance performance. To disable caching for development purposes, use the -c-1 option.

Exploring Available Options

http-server comes with a range of options to customize its behavior, offering flexibility for various use cases. Here’s a table summarizing the available options:

Command	Description	Defaults
-p or --port	Specifies the port number. Use -p 0 for automatic port assignment starting from 8080, or utilize process.env.PORT.	8080
-a	Defines the address to bind to.	0.0.0.0
-d	Enables or disables directory listings.	true
-i	Toggles autoIndex display for directory listings.	true
-g or --gzip	Enables serving gzipped files (e.g., .js.gz for .js) when available and accepted by the client. Prioritizes brotli if both are enabled.	false
-b or --brotli	Enables serving brotli compressed files (e.g., .js.br for .js) when available and client accepts br encoding. Brotli is prioritized over gzip if both are active.	false
-e or --ext	Sets the default file extension if none is provided in the URL.	html
-s or --silent	Suppresses log messages in the output.
--cors	Enables Cross-Origin Resource Sharing (CORS) by adding the Access-Control-Allow-Origin header.
-o [path]	Automatically opens a browser window upon server start, optionally navigating to a specific URL path.
-c	Configures cache duration (in seconds) for the cache-control max-age header. Use -c-1 to disable caching entirely.	3600
-U or --utc	Uses UTC time format for log messages.
--log-ip	Activates logging of client IP addresses.	false
-P or --proxy	Proxies unresolved local requests to a specified URL. Example: -P http://someurl.com.
--proxy-options	Allows passing proxy options as nested dotted objects, leveraging node-http-proxy options. Example: --proxy-options.secure false.
--username	Sets the username for basic authentication.
--password	Sets the password for basic authentication.
-S, --tls or --ssl	Enables HTTPS (TLS/SSL) for secure serving.	false
-C or --cert	Specifies the path to the SSL certificate file.	cert.pem
-K or --key	Specifies the path to the SSL key file.	key.pem
-r or --robots	Automatically serves a /robots.txt file with default content: User-agent: *nDisallow: /.	false
--no-dotfiles	Prevents serving dotfiles (files starting with a dot).
--mimetypes	Specifies a custom .types file for defining MIME types.
-h or --help	Displays this options list and exits.
-v or --version	Prints the http-server version and exits.

Magic Files for Enhanced Functionality

http-server recognizes special filenames to provide enhanced features:

• index.html: When a directory is requested, http-server will serve index.html as the default file, ideal for website landing pages.
• 404.html: If a requested file is not found, http-server will serve 404.html. This is particularly useful for Single-Page Applications (SPAs) to serve the application’s entry point for all undefined routes, enabling client-side routing.

Implementing Catch-All Redirects

For scenarios requiring catch-all redirects, you can cleverly utilize the index page as a proxy:

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

Adding a ? at the end of the proxy URL effectively redirects all requests to the index page, a neat trick contributed by @houston3.

Securing Your Server with TLS/SSL (HTTPS)

To enable HTTPS for secure connections, you’ll need to set up TLS/SSL. First, ensure that openssl is installed on your system. Generate key.pem and cert.pem files using the following command:

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

When prompted for the Common Name, use 127.0.0.1 if you intend to install the certificate in your OS or browser’s root certificate store for trusted access. This command creates a certificate-key pair valid for approximately 10 years.

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

http-server -S -C cert.pem

For private keys with passphrases, include the passphrase in the openssl command using -passout, for example:

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

The passphrase will be read from the NODE_HTTP_SERVER_SSL_PASSPHRASE environment variable for security.

Upon successful setup, the output will indicate that http-server is serving over HTTPS, providing secure access to your static files.

Development Environment Setup

For contributing to http-server‘s development or running a development instance, follow these steps:

1. Clone the repository locally.

2. Navigate into the cloned directory in your terminal.

3. Install dependencies using npm:

   npm install

4. Start the development server:

   npm start

Now, you can access the development server at http://localhost:8080 and view the demo content located in the ./public folder, ensuring you have a local testing environment mirroring the live http-server behavior.