# http-server — Zero-Config Static File Server for Development

> A simple, zero-configuration command-line HTTP server for serving static files. Ideal for quickly previewing HTML/CSS/JS projects, testing single-page applications locally, and serving build artifacts during development.

## Install

Save in your project root:

# http-server — Zero-Config Static File Server for Development

## Quick Use
```bash
npx http-server ./dist
# Or install globally
npm install -g http-server
http-server -p 8080
```

## Introduction
http-server is a zero-configuration command-line HTTP server for Node.js. It serves static files from any directory, making it one of the simplest ways to preview web projects, test build output, or host files locally during development without configuring Nginx, Apache, or a framework dev server.

## What http-server Does
- Serves any directory as a static file server with a single command
- Supports HTTPS via self-signed certificates or custom TLS key/cert pairs
- Enables CORS headers with a single flag for cross-origin API testing
- Provides gzip and brotli compression for served files
- Falls back to `index.html` for single-page application routing with the `--proxy` flag

## Architecture Overview
http-server is a thin wrapper around Node.js's built-in HTTP module combined with the `union` middleware framework and `ecstatic` static file serving library. When invoked, it binds to a port, resolves file paths relative to the specified root directory, and serves matching files with appropriate MIME types. Directory listings are generated automatically when no index file exists.

## Self-Hosting & Configuration
- Run with `npx http-server` for instant usage without global installation
- Use `-p` to specify a custom port (default is 8080)
- Enable HTTPS with `-S` and optionally provide `-C` (cert) and `-K` (key) files
- Set `-c-1` to disable caching during active development
- Use `--proxy http://localhost:8080?` to redirect 404s to the root for SPA client-side routing

## Key Features
- True zero-configuration: just point it at a directory and go
- HTTPS support with automatic self-signed certificate generation
- CORS enabled via `--cors` flag for frontend development against local APIs
- Gzip compression support to simulate production-like file serving
- Lightweight with no build step, framework, or config file required

## Comparison with Similar Tools
- **serve (Vercel)** — similar zero-config static server with built-in SPA support and cleaner directory listings; http-server has been around longer
- **live-server** — adds live reload on file changes; http-server requires a separate file watcher
- **Python http.server** — built into Python but lacks CORS, HTTPS, and compression options
- **BrowserSync** — provides live reload and multi-device sync; heavier than http-server for simple file serving

## FAQ
**Q: Can http-server serve single-page applications?**
A: Yes, use the `--proxy` flag to redirect unmatched routes back to `index.html`.

**Q: How do I enable HTTPS?**
A: Pass the `-S` flag. http-server will generate a self-signed certificate automatically, or you can supply your own with `-C` and `-K`.

**Q: Does http-server support live reload?**
A: No, http-server is a static file server only. For live reload, combine it with a file watcher like `nodemon` or use `live-server` instead.

**Q: How do I disable caching?**
A: Use `-c-1` to set the cache time to negative one second, effectively disabling browser caching.

## Sources
- https://github.com/http-party/http-server
- https://www.npmjs.com/package/http-server

---
Source: https://tokrepo.com/en/workflows/asset-0486fa5b
Author: AI Open Source