light-server

library2.9.1jsnpmunverified

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.

web-framework http-networking devops

npm install light-server

github ↗package ↗

INSTALL

IMPORT

SIG · LIGHT-SERVER

light-server

web-frameworkjavascriptv2.9.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (CLI)

✓ npx light-server -s . -p 4000

✗ require('light-server')

light-server is a CLI tool, not a library. Use it via npx or npm scripts.

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"

light-server --version

Debug

Known issues

deprecatedopn 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.

affects: >=2.0.0

gotchaWatch 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.

affects: ALL

gotchaLive 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.

affects: ALL

gotchaThe --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.

affects: ALL

gotchaProxy 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.

affects: ALL

Errors

Common errors & fixes

Error loading .lightserverrc: Invalid config

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}.

Watch error: cannot read property 'on' of undefined

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.

Port 4000 is already in use

Another process is using the specified port

fix

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

Cannot find module 'light-server'

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: listen EADDRINUSE: address already in use :::4000

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)

Upgrade

Version history

2.9.1latest on npm

Audit

Dependencies

minimistrequiredCLI argument parsing

morganrequiredHTTP request logging

opnrequiredOpen browser on startup

gazerequiredFile watching with globs

serve-staticrequiredStatic file serving

connectrequiredHTTP server framework

http-proxyrequiredProxy functionality

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/txchen/light-server ↗

packagehttps://www.npmjs.com/package/light-server ↗