livelocalhost

LiveLocalhost

GitHub | npm | sponsor | craigbuckler.com | BlueSky | X

A simple localhost development web server with hot reloading. It serves web files from any local directory, watches for file changes, and triggers automated browser refreshes. You can run it from the command line or in a Node.js application.

Quick start

Run LiveLocalhost from the command line to serve files from the current directory:

npx livelocalhost

then open http://localhost:8000/ in your browser.

You can also install it globally:

npm install livelocalhost -g

and run using:

livelocalhost

or

llh

To use a different port and directory:

llh -p 8888 -d ./path/

Command line configuration

Add -? or --help for CLI help. Options:

parameter	description
-v, --version	show application version
-?, --help	show CLI help
-E, --helpenv	show .env/environment variable help
-A, --helpapi	show Node.js API help
-e, --env <file>	load defaults from an .env file
-p, --serveport <port>	HTTP port (default 8000)
-d, --servedir <dir>	directory to serve (./)
-r, --reloadservice <path>	path to reload service (/livelocalhost.service)
-j, --hotloadJS	enable hot reloading of JavaScript files (false)
-w, --watchDebounce <ms>	debounce time for file changes (default 600)
-l, --accessLog	show server access log (false)

Serve files from ./build/ at http://localhost:8080 and show the access log:

llh --serveport 8080 -d ./build/ -l

The first two non-dashed parameters are presumed to be the port and directory:

llh 8080 ./build/ -l

Stop the server with Ctrl | Cmd + C.

Environment variable configuration

The server can be configured with environment variables. Add -E or --helpenv for help. Variables:

env variable	description
SERVE_PORT=<port>	HTTP port (default 8000)
BUILD_DIR=<dir>	directory to serve (./)
RELOAD_SERVICE=<path>	path to reload service (/livelocalhost.service)
HOTLOAD_JS=<true|false>	enable hot reloading of JavaScript files (false)
WATCH_DEBOUNCE=<num>	debounce time for file changes (default 600)
ACCESS_LOG=<true|false>	show server access log (false)

Variables can be defined in a file, e.g.

# example .env file
SERVE_PORT=8080
BUILD_DIR=./build/
ACCESS_LOG=true

then loaded:

llh --env .env

Note that CLI arguments take precedence over environment variables.

Node.js API usage

You can use LiveLocalhost in any Node.js project. Add -A or --helpapi for help.

Install in your project:

npm install livelocalhost --save-dev

(--save-dev ensures it's only available in development)

Import the module into any JavaScript file (such as index.js):

import { livelocalhost } from 'livelocalhost';

set options as necessary, e.g.

livelocalhost.serveport     = 8080;       // HTTP port
livelocalhost.servedir      = './build/'; // directory to serve
livelocalhost.reloadservice = '/reload';  // path to reload service
livelocalhost.hotloadJS     = true;       // hot reload JS
livelocalhost.watchDebounce = 2000;       // debounce time
livelocalhost.accessLog     = true;       // show server logs

(If not set, options fall back to environment variables then defaults.)

Execute the .start() method to start the server:

livelocalhost.start();

Launch your application as normal (node index.js) and open the server URL in your browser.

Hot reloading

Browser hot reloading is available when:

• the application has permission to watch OS files, and
• --reloadservice is a valid URL path starting /.

The default Server Sent Events service path for hot reloading is /livelocalhost.service. A client-side script at /livelocalhost.service.js is injected into all HTML files which automatically refreshes the browser:

• CSS changes are hot reloaded without a full page refresh
• HTML changes trigger a full page refresh
• JavaScript changes trigger a full page refresh when --hotloadJS is enabled (off by default).

You need only change --reloadservice when the default path is in use or you want to disable hot reloading (set any value that does not start with /).

Watch debouncing

When a file is changed, LiveLocalhost waits 600ms. A hot reload is only triggered if no other files change within that time.

You can change the delay time using --watchDebounce. Note that very low settings can make reloading slower.