Guide · Open source
How to use http-server: serve a folder in your browser
Updated · written with AI from the project's own documentation and checked against our catalogue data
http-server is a free, open-source command-line tool that serves a folder from your computer as a website you can open in a browser, with no configuration file. This guide is for front-end developers, students and anyone who wants to preview a static site or built HTML, CSS and JavaScript folder. By the end you will know how to install it, start it on a folder and use the options for caching, CORS, proxying and HTTPS.
http-serverhttp-party/http-server · ★ 14.2k · MIT Install options & downloads Quick start
- 1Install Node.js. http-server needs Node.js. The README does not give a required version, so use a current supported release.
- 2Install or run http-server. Run npx http-server for no install, or npm install --global http-server to make the command available everywhere.
- 3Start the server on your folder. Run http-server followed by the folder path, such as ./public or ./dist.
- 4Open the local address. Visit http://localhost:8080 in your browser to view the folder.
- 5Add options as needed. Use flags such as -p for port, -c-1 to disable caching, or --cors for cross-origin requests.
- 6Enable HTTPS if you need it. Create key.pem and cert.pem with openssl, then run http-server -S -C cert.pem.
Install http-server with npm, Homebrew or npx
http-server is installed through a package manager and needs Node.js. The README does not specify a Node.js version, so check your installed version if you hit problems.
You can run it without installing anything using npx, or install it globally so the http-server command works from any folder.
- Run on demand with npx (no install step)
- Install globally via npm so the command is available anywhere
- Install with Homebrew using brew install http-server
- Add it as a dependency of your own npm package with npm install http-server
- Docker: the README says no public image is provided, but you can build one with the included Dockerfile
npm install --global http-serverStart the server on a folder
Run http-server with an optional path. If you give no path, it uses ./public when that folder exists, and ./ otherwise. Once it starts, open http://localhost:8080 in your browser.
To serve a specific folder, pass its path, and add options after it. Caching is on by default, so add -c-1 if you want to turn it off while developing.
- Default port is 8080
- Use -p 0 to look for an open port, starting at 8080
- Default address is 0.0.0.0
- Press CTRL-C to stop the server
npx http-server [path] [options]Use common options for development
Most day-to-day use needs only a few flags. The full option list is in the README and printed by http-server -h.
The --cors flag adds the Access-Control-Allow-Origin header, which helps when a page on one origin calls the server. -o opens a browser window after startup, and -s silences log messages.
- -p or --port sets the port
- -o [path] opens the browser, optionally at a URL path such as /other/dir/
- -c sets cache time in seconds, e.g. -c10; -c-1 disables caching
- -t sets the connection timeout in seconds; -t0 disables it
- -e or --ext sets the default file extension if none is supplied (default html)
- -s or --silent suppresses log messages
- --cors enables CORS; --coop and --private-network-access add their own headers
- -H or --header adds an extra response header, and can be used several times
- --no-dotfiles hides dotfiles
http-server ./dist -p 3000 -o --cors -c-1Serve a single-page app with magic files
http-server treats two file names specially. index.html is served for any directory request. 404.html is served when a file is not found, which is useful for single-page app (SPA) hosting because the entry page handles routing.
The README also describes a catch-all redirect trick: use the index page as the proxy, noting the ? at the end of the URL.
- index.html: default file for directory requests
- 404.html: served when a file is not found
- -dir-overrides-404 controls whether -d directory listings override 404.html (default false)
http-server --proxy http://localhost:8080?Run an HTTPS server for local testing
To serve over TLS, you need openssl installed and a key.pem and cert.pem file. The README gives an openssl command that creates both. When asked for Common name, use 127.0.0.1 if you want to trust the certificate in your OS or browser store.
Start the server with -S to enable SSL and -C to point at your certificate. If your private key has a passphrase, the README says it is read only from the NODE_HTTP_SERVER_SSL_PASSPHRASE environment variable.
- -S, --tls or --ssl enables HTTPS
- -C or --cert sets the certificate file (default cert.pem)
- -K or --key sets the key file (default key.pem)
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
http-server -S -C cert.pemProxy requests and add basic auth
Use -P or --proxy to forward requests that cannot be resolved locally to another URL. Add --proxy-all to forward every request to the proxy target instead of serving local files.
For basic authentication, the README lists --user (or --username) and --password. Use --allowed-hosts to limit which hosts can reach the server.
- -P or --proxy: proxy unresolved requests to a URL
- --proxy-all: forward every request to the proxy
- --proxy-config: pass a .json config file or stringified JSON
- --user / --username and --password: basic authentication
- --allowed-hosts: comma-separated list of allowed hosts
http-server -P http://someurl.comWhat people use it for
- Preview a static site or single-page app before deploying it
- Test a built HTML, CSS and JavaScript folder without setting up a full web server
- Learn how web servers and HTTP work with a simple, hackable tool
- Run a simple proxy or HTTPS server for local testing
Frequently asked questions
Is http-server free to use?
http-server is released under the MIT licence, as stated in the project's listing. The source does not describe any paid tier.
What do I need to run http-server?
You need Node.js installed. The README does not specify a Node.js version, so check the project's npm page or package requirements if you need one.
How do I install http-server?
Install it globally with npm install --global http-server, or run it without installing using npx http-server [path] [options]. Homebrew users can run brew install http-server.
Why does my browser show old files after I change them?
Caching is on by default with a max-age of 3600 seconds. Add -c-1 to disable caching while you develop.
How is http-server different from serve or live-server?
The source lists serve, live-server, lite-server and python -m http.server as comparable projects but does not compare their features. Check each project's documentation to decide which fits your workflow.
Can http-server run server-side code like PHP or Node apps?
No. The source describes http-server as a static file server that can proxy requests, not one that runs application code. Use a proxy option to forward requests to another server.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
http-server suits front-end developers and students who need to preview static files, single-page apps or a quick HTTPS or proxy setup on their own machine. If you need dynamic server-side logic or a managed hosting service with scaling and monitoring, pick a different tool.
Install options & downloads