lite-server

library2.6.1jsnpmunverified

Lightweight development-only Node.js server for SPAs, wrapping BrowserSync with automatic HTML5 history API fallback, live reload, and CSS injection via WebSocket. Version 2.6.1 (latest) as of 2023, maintained infrequently (last release 2021). Key differentiator: integrates BrowserSync with connect-history-api-fallback middleware out of the box, solving deep-linking for Angular/React/Vue SPAs with minimal config. Unlike plain BrowserSync, it defaults to serving index.html for unknown routes. Primarily used via npm scripts or npx, supports custom BrowserSync config via bs-config.json/js.

web-framework devops

npm install lite-server

github ↗package ↗

INSTALL

IMPORT

SIG · LITE-SERVER

lite-server

web-frameworkjavascriptv2.6.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.

lite-server (CLI)

✓ npx lite-server

✗ npm run lite-server without script entry

Use as CLI tool, not programmatic API. Install locally and run via npm script.

bs-config (module.exports)

✓ module.exports = { server: { baseDir: './src' } }

✗ export default { ... } (ESM syntax not supported)

Config file must be CommonJS (bs-config.js) or JSON (bs-config.json). ESM not supported.

CLI options

✓ lite-server -c my-config.js --baseDir=dist

✗ lite-server --config my-config.js --basedir=dist (typo in baseDir)

Use -c or --config= for config file, --baseDir= for base directory.

Basic setup: add lite-server to package.json scripts as 'dev', install locally, then run with npm run dev.

{ "scripts": { "dev": "lite-server" } } // Then run: npm install lite-server --save-dev && npm run dev

lite-server --version

Debug

Known issues

gotchalite-server is intended for development only; do not use in production.

fix

Use a proper production server like Express, Nginx, or serve-static.

affects: *

gotchaConfig file must be CommonJS (module.exports) for .js files; ESM (export default) not supported.

fix

Use module.exports = { ... } in bs-config.js.

affects: >=2.0.0

deprecatedGreenkeeper badge in README refers to deprecated service; project may not have active dependency updates.

fix

Monitor dependencies manually or use Dependabot/Renovate.

affects: *

gotchaDefault base directory is current working directory; ensure index.html exists or specify with --baseDir.

fix

Run from project root or use --baseDir='dist'

affects: *

gotchaWhen using --baseDir CLI option, ensure path is relative to current working directory.

fix

Use absolute or correct relative path.

affects: *

breakingThe library is in maintenance mode with no active development; newer versions may not be released.

fix

Consider alternatives like Vite, webpack-dev-server, or @angular-devkit/build-angular if issues arise.

affects: >=2.6.1

Errors

Common errors & fixes

Error: Cannot find module 'browser-sync'

Missing dependency; lite-server installs browser-sync as a dependency, but npm may fail.

fix

Ensure lite-server is installed correctly; try 'npm install lite-server --save-dev'.

TypeError: Cannot read property 'indexOf' of undefined

Config file uses invalid syntax or missing exports.

fix

Check bs-config.js has module.exports = { ... }; for JSON file, ensure valid JSON.

Error: listen EADDRINUSE :::3000

Default port 3000 already in use by another process.

fix

Specify a different port in bs-config.json: { "port": 8080 }

Error: No such file or directory: '/path/to/project/index.html'

Base directory does not contain index.html.

fix

Set correct baseDir in config or use --baseDir pointing to folder with index.html.

Error: Cannot find module 'connect-history-api-fallback'

Missing dependency; lite-server may not install correctly.

fix

Reinstall lite-server: npm install lite-server --save-dev

Upgrade

Version history

2.6.1latest on npm

Audit

Dependencies

browser-syncrequiredCore server providing live reload, CSS injection, WebSocket sync

connect-history-api-fallbackrequiredMiddleware for HTML5 history API fallback to index.html

yargsrequiredCLI argument parsing for --config, --baseDir, etc.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/johnpapa/lite-server ↗

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