light-server

2.9.1 verified Sat Apr 25 auth: no javascript maintenance

A lightweight CLI static HTTP server with file-watching, custom command execution and live-reload capabilities. Version 2.9.1 (latest as of 2023) is a stable release with no active development cadence; last published 5 years ago. Key differentiators against alternatives like BrowserSync: minimal dependencies (~100KB vs >50MB), no build tool integration required, CLI-only usage designed for npm scripts, and built-in live reload with CSS injection without browser plugins. Supports HTTP/2, proxy, SPA history API fallback, and negative glob patterns. Best suited for static site development needing simple server + reload.

Common errors

error Error loading .lightserverrc: Invalid config ↓

cause Config file is not valid JSON or has wrong structure

fix

Ensure .lightserverrc is valid JSON with the same keys as CLI options, e.g., {"serve": ".", "port": 4000}.

error Watch error: cannot read property 'on' of undefined ↓

cause Watched directory does not exist or gaze fails to initialize

fix

Check that the directory in the watch expression exists; use absolute paths if possible.

error Port 4000 is already in use ↓

cause Another process is using the specified port

fix

Use a different port with -p, or kill the existing process: lsof -ti:4000 | xargs kill

error Cannot find module 'light-server' ↓

cause Attempting to require light-server as a Node.js module instead of running as CLI

fix

Run via CLI: npx light-server ... or install globally: npm install -g light-server

error Error: listen EADDRINUSE: address already in use :::4000 ↓

cause Same as port in use, but more precise error from Node.js

fix

Use -p to specify an available port, or stop the process with kill -9 $(lsof -t -i:4000)

Warnings

deprecated opn package has been deprecated and renamed to open. May cause security audit warnings. ↓

fix No fix expected from maintainer; consider switching to a maintained alternative like live-server or http-server with chokidar-cli.

gotcha Watch expressions with spaces in file paths will break. The # delimiter is used without escaping. ↓

fix Avoid spaces in watched paths; use Unix-style escaping or change directory structure.

gotcha Live reload injection only works on HTML files. Other file types (e.g., PHP, ASP) do not inject the client script. ↓

fix Serve only static HTML during development, or disable live reload and use manual refresh.

gotcha The --servePrefix option changes the URL path but does NOT affect the file system path. Files are still served from the directory specified by -s. ↓

fix Set -s to the actual file directory; use --servePrefix only for URL rewriting.

gotcha Proxy option (-x) only proxies when the static file is NOT found (404). It does not proxy all requests. ↓

fix If you need all requests proxied, use a dedicated proxy tool or configure light-server with --proxypath to selectively proxy.

Install

npm install light-server

yarn add light-server

pnpm add light-server

Imports

default (CLI)
wrong
```
require('light-server')
```
correct
```
npx light-server -s . -p 4000
```
light-server is a CLI tool, not a library. Use it via npx or npm scripts.

Quickstart

Starts a static server on port 4000 serving current directory, watches CSS files and triggers CSS reload without full page refresh.

npx light-server -s . -p 4000 -w "**/*.css # # reloadcss"