Command line
Run the server from a terminal.
Install, serve, expose, tune, and stop the CLI. Every supported input and exit path is documented here.
Install and run
Choose how the command is available.
| Use | Command | What it does |
|---|---|---|
| Global command | npm install --global node-http-server | Adds node-http-server to the active npm environment. |
| One-off run | npx node-http-server --root ./public | Runs the package command without relying on a global install. |
| Repository script | npm start -- --root ./public | Runs this repository's CLI entry and forwards flags after --. |
shell · local static root
node-http-server --root ./public --port 8080Expected output
node-http-server listening at http://127.0.0.1:8080
The printed URL uses the actual listener address and port. With --port 0, the operating system selects a free port and that assigned port appears in the output.
Common tasks
Copy the command for the job.
| Task | Command | Expected behavior |
|---|---|---|
| Serve current directory | node-http-server | Local HTTP on 127.0.0.1:8080. |
| Serve another directory | node-http-server --root ./public | Paths resolve from the current working directory. |
| Pick a local port | node-http-server --port 9000 | Local HTTP on port 9000. |
| Pick a free port | node-http-server --port 0 | Prints the operating-system-assigned port. |
| Accept network traffic | node-http-server --host 0.0.0.0 | Binds all IPv4 interfaces; firewall and network policy still apply. |
| Require one Host value | node-http-server --domain example.test | Other Host values receive 421; this does not set DNS or the bind address. |
| Serve an SPA | node-http-server --root ./dist --spa --compression | Missing extensionless HTML routes use the index; eligible responses negotiate compression. |
| Use another SPA file | node-http-server --spa=app.html | Uses app.html as the fallback. |
| Limit bodies to 1 MiB | node-http-server --max-body 1048576 | Oversized request bodies stop with 413. |
| Disable one timeout | node-http-server --request-timeout false | false, off, and 0 disable numeric timeout/body controls. |
| Allow client caching | node-http-server --cache | Turns off the default no-cache directives. |
| Serve intentional dotfiles | node-http-server --root ./public --allow-dotfiles | Allows every dot-prefixed segment in that root, including /.well-known; audit the root first. |
| Write request logs | node-http-server --log ./logs/requests.ndjson | Appends one JSON record per line; the parent directory must exist. |
| Inspect activity | node-http-server --verbose | Prints normalized configuration and listener activity. |
SPA filename syntax: use
--spa=app.html. With --spa app.html, app.html becomes the positional root when no root is set, or becomes an unknown argument. --spa=false means a fallback file literally named false; it does not disable SPA fallback.Complete option reference
Every documented flag.
| Option | Default | Sets | Accepted value / note |
|---|---|---|---|
-p, --port <port> | 8080 | port | Nonnegative number; deployment requires an integer from 0–65535. |
-r, --root <path> | current directory | root | Existing directory, resolved from the working directory. |
--host <address> | 127.0.0.1 | host | Nonempty listen address. |
--domain <hostname> | 0.0.0.0 | domain | Primary accepted Host; not a network bind or DNS setting. |
--index <file> | index.html | server.index | Directory index filename; there is no directory listing when it is missing. |
--no-cache | on | server.noCache=true | Explicitly sends default no-cache directives. |
--cache | off | server.noCache=false | Omits the default no-cache header; it does not add a cache lifetime. |
--allow-dotfiles | off | server.allowDotfiles=true | Explicit all-dotfile opt-in; --allow-dotfiles=false restores the default denial. |
--spa[=<file>] | off | server.spaFallback | No value uses the index; custom filename requires =. |
--compression | off | server.compression=true | Static eligible responses at least 1024 bytes; not byte ranges. |
--max-body <bytes|false> | unlimited | server.maxRequestBodyBytes | Nonnegative bytes; false, off, or 0 is unlimited. |
--timeout <ms|false> | 30000 | server.timeout | Socket inactivity milliseconds; false/off/0 disables. |
--request-timeout <ms|false> | 300000 | server.requestTimeout | Whole-request milliseconds; false/off/0 disables. |
--headers-timeout <ms|false> | 60000 | server.headersTimeout | Header milliseconds; false/off/0 disables. |
--keep-alive-timeout <ms|false> | 5000 | server.keepAliveTimeout | Keep-alive milliseconds; false/off/0 disables. |
--log <path> | off | log | NDJSON append destination. |
-v, --verbose | off | verbose=true | Prints operational details. |
-h, --help | — | help output | Parses all input first, then prints help and exits 0. |
--version | — | version output | Prints the package version and exits 0. Help wins when both are set. |
Input syntax
Modern flags and compatible input.
| Form | Example | Parsing rule |
|---|---|---|
| Long option + value | --root ./public | The next token supplies a value for value-taking options. |
| Long option + equals | --port=9000 | Equivalent to the separated form. |
| Short option | -p 9000 | -p, -r, -v, and -h are supported. |
| Positional root | node-http-server ./public | The first bare token becomes root; later bare tokens fail. |
| v8 key=value | root=./public port=9000 verbose=true | Compatibility form; sequential inputs are last-wins. |
| Legacy camelCase aliases | requestTimeout=false | noCache, allowDotfiles, spaFallback, maxRequestBodyBytes, requestTimeout, headersTimeout, and keepAliveTimeout map to modern options. |
Ordering: options are processed from left to right; the last value for the same setting wins. All arguments are validated before help or version output.
Parsing details: boolean words are lowercase
true/false. A flag needs equals to turn it off—for example --compression=false, not --compression false. Short options cannot be bundled. If a value starts with -, use equals, such as --root=-name. --cache=<anything> still enables caching.Output and process exits
Use exit status as the contract.
| Condition | Output | Exit status |
|---|---|---|
| Listener ready | node-http-server listening at http://ADDRESS:PORT | Process remains running. |
| Help or version | Requested information on stdout. | 0 |
| Argument parse error | Error plus Run node-http-server --help for usage. | 2 |
| Deploy/listener/close failure | Error message on stderr; sibling listeners close after listener failure. | 1 |
| Request-level 4xx/5xx or log-write failure | The request completes; verbose mode reports asynchronous log failures. | Server keeps running. |
SIGINT / Ctrl+C | Listeners close. | 130 |
SIGTERM | Listeners close. | 0 |
shell · verify inputs without starting
node-http-server --help
node-http-server --versionTroubleshooting
Read the first failure literally.
| Symptom | Likely cause | Next check |
|---|---|---|
EADDRINUSE | Another process owns the port. | Choose another --port or stop the conflicting process. |
EACCES | The address/port is not permitted. | Use an allowed unprivileged port and confirm host permissions. |
root must be a directory | The path is missing or is a file. | Resolve the root from the current working directory. |
421 Misdirected Request | The Host header does not match domain. | Fix the request Host or remove/change --domain. |
| Remote machine cannot connect | Loopback bind, firewall, or wrong address. | Set --host 0.0.0.0 deliberately, allow the port, then connect to the machine's network address—not 0.0.0.0. |
| SPA file not selected | The custom file was separated by a space. | Use --spa=app.html. |
Dot-prefixed path returns 403 | Dotfiles are blocked by default. | Move the public file to a normal path, or use --allow-dotfiles only with a dedicated audited root. |
| Log errors appear later | Parent directory missing or write denied. | Create/protect the directory and use --verbose to surface asynchronous failures. |
Unknown option: config | The CLI has no JSON config loader. | Use the module API; a bare config.json is treated as the root path. |
CLI boundary
Use the library for object configuration.
The CLI intentionally covers common static-server operations. It does not load configuration JSON or expose every nested object.
| Needs the module API | Configuration/API link |
|---|---|
| HTTPS keys and certificates | https configuration |
| Multiple domain roots | domains mapping |
| MIME overrides, rejected/restricted extensions | contentType and restrictedType |
| Custom error bodies/headers | errors |
| Compression threshold | server.compressionThreshold |
| Log bodies or custom logger functions | Logging configuration |
| Hooks, multiple instances, lifecycle control | Library API |