{"id":17701,"library":"http-serve","title":"http-serve: Command-line HTTP Server","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/dkarmalita/http-serve","tags":["javascript","cli","command","http","https","gzip","gz","fallback"],"install":[{"cmd":"npm install http-serve","lang":"bash","label":"npm"},{"cmd":"yarn add http-serve","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-serve","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { serve } from 'http-serve'","symbol":"http-serve","correct":"npm i -g http-serve\nhttp-serve . -p 8080"},{"note":"For project-specific use without global installation, `npx` is the recommended method to execute the CLI directly from `node_modules`.","wrong":"node_modules/http-serve/bin/http-serve","symbol":"http-serve (via npx)","correct":"npx http-serve . -p 8080 --gzip"},{"note":"Integrating `http-serve` into `package.json` scripts allows for consistent project-level command execution and configuration.","wrong":"node http-serve.js","symbol":"http-serve (package.json script)","correct":"// package.json\n{\n  \"scripts\": {\n    \"serve\": \"http-serve ./dist -p 8081 --cors --fallback /index.html\"\n  }\n}\n// Then run: npm run serve"}],"quickstart":{"code":"mkdir my-project\ncd my-project\n\n# 1. Initialize project and install http-serve\nnpm init -y\nnpm i -D http-serve\n\n# 2. Create some static files\nmkdir public\necho '<h1>Hello from http-serve!</h1><p>This is your index page.</p>' > public/index.html\necho 'console.log(\"This is an asset.\");' > public/app.js\necho 'alert(\"404 Not Found!\");' > public/404.html\n\n# 3. Add a 'start' script to package.json\n#    (replace existing 'test' script or add to 'scripts' object)\nnpm pkg set scripts.start=\"http-serve ./public -p 8080 --ext html --gzip --fallback /404.html -o --silent\"\n\n# 4. Run the server\nnpm start\n\n# This command starts an HTTP server on http://localhost:8080,\n# serves content from './public', enables gzip (if .gz files exist),\n# redirects 404s to /404.html, and opens the browser automatically.","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The `--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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always specify the directory you intend to serve, e.g., `http-serve ./dist` or `http-serve .`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the documentation for `http-serve` specifically to understand its unique options and behaviors, especially if migrating from or comparing against `http-server`.","message":"`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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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>`.","cause":"`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.","error":"sh: http-serve: command not found"},{"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.","cause":"Another process on your system is already listening on the specified port (8080 by default).","error":"Error: listen EADDRINUSE: address already in use :::8080"},{"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.","cause":"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).","error":"ERR_SSL_PROTOCOL_ERROR (in browser) or related HTTPS connection issues"},{"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.","cause":"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.","error":"Files are not being served with gzip compression."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}