lite-server

2.6.1 verified Sat Apr 25 auth: no javascript maintenance

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.

Common errors

error Error: Cannot find module 'browser-sync' ↓

cause 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'.

error TypeError: Cannot read property 'indexOf' of undefined ↓

cause Config file uses invalid syntax or missing exports.

fix

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

error Error: listen EADDRINUSE :::3000 ↓

cause Default port 3000 already in use by another process.

fix

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

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

cause Base directory does not contain index.html.

fix

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

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

cause Missing dependency; lite-server may not install correctly.

fix

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

Warnings

gotcha lite-server is intended for development only; do not use in production. ↓

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

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

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

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

fix Monitor dependencies manually or use Dependabot/Renovate.

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

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

gotcha When using --baseDir CLI option, ensure path is relative to current working directory. ↓

fix Use absolute or correct relative path.

breaking The 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.

Install

npm install lite-server

yarn add lite-server

pnpm add lite-server

Imports

lite-server (CLI)
wrong
```
npm run lite-server without script entry
```
correct
```
npx lite-server
```
Use as CLI tool, not programmatic API. Install locally and run via npm script.
bs-config (module.exports)
wrong
```
export default { ... } (ESM syntax not supported)
```
correct
```
module.exports = { server: { baseDir: './src' } }
```
Config file must be CommonJS (bs-config.js) or JSON (bs-config.json). ESM not supported.

CLI options

wrong

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

correct

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

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

Quickstart

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