lite-server
Lightweight development only node server that serves a web app, opens it in the browser, refreshes when html or javascript change, injects CSS changes using sockets, and has a fallback page when a route is not found.Why
BrowserSync does most of what we want in a super fast lightweight development server. It serves the static content, detects changes, refreshes the browser, and offers many customizations.When creating a SPA there are routes that are only known to the browser. For example,
/customer/21
may be a client side route for an Angular app. If this route is entered manually or linked to directly as the entry point of the Angular app (aka a deep link) the static server will receive the request, because Angular is not loaded yet. The server will not find a match for the route and thus return a 404. The desired behavior in this case is to return the index.html
(or whatever starting page of the app we have defined). BrowserSync does not automatically allow for a fallback page. But it does allow for custom middleware. This is where lite-server
steps in.lite-server
is a simple customized wrapper around BrowserSync to make it easy to serve SPAs.Installation and Usage
The recommended installation method is a local NPM install for your project:npm install lite-server --save-dev
yarn add lite-server --dev # or yarn
...and add a "script" entry within your project's
package.json
file:# Inside package.json...
"scripts": {
"dev": "lite-server"
},
With the above script entry, you can then start
lite-server
via:npm run dev
Other options for running locally installed NPM binaries is discussed in this Stack Overflow question: How to use package installed locally in nodemodules
Using on the fly
lite-server can be used withnpx
npx lite-server
Global Installation
lite-server can be also installed globally, if preferred:npm install --global lite-server
# To run:
lite-server
Custom Configuration
The default behavior serves from the current folder, opens a browser, and applies a HTML5 route fallback to./index.html
.lite-server uses BrowserSync, and allows for configuration overrides via a local
bs-config.json
or bs-config.js
file in your project.You can provide custom path to your config file via
-c
or --config=
run time options:lite-server -c configs/my-bs-config.js
For example, to change the server port, watched file paths, and base directory for your project, create a
bs-config.json
in your project's folder:{
"port": 8000,
"files": ["./src/**/*.{html,htm,css,js}"],
"server": { "baseDir": "./src" }
}
You can also provide custom path to your base directory
--baseDir=
run time options:lite-server --baseDir="dist"
A more complicated example with modifications to the server middleware can be done with a
bs-config.js
file, which requires the module.exports = { ... };
syntax:module.exports = {
server: {
middleware: {
// overrides the second middleware default with new settings
1: require('connect-history-api-fallback')({
index: '/index.html',
verbose: true,
}),
},
},
};
The
bs-config.js
file may also export a function that receives the lite-server Browsersync instance as its only argument. While not required, the return value of this function will be used to extend the default lite-server configuration.module.exports = function (bs) {
return {
server: {
middleware: {
// overrides the second middleware default with new settings
1: require('connect-history-api-fallback')({
index: '/index.html',
verbose: true,
}),
},
},
};
};
NOTE: Keep in mind that when using middleware overrides the specific middleware module must be installed in your project. For the above example, you'll need to do:
npm install connect-history-api-fallback --save-dev
...otherwise you'll get an error similar to:
Error: Cannot find module 'connect-history-api-fallback'
Another example: To remove one of the default middlewares, such as
connect-logger
, you can set it's array index to null
:module.exports = {
server: {
middleware: {
0: null, // removes default `connect-logger` middleware
},
},
};
A list of the entire set of BrowserSync options can be found in its docs:
Testing
When usinglite-server
to run end to end tests, we may not want to log verbosely. We may also want to prevent the browser from opening. These options in the bs-config.js
will silence all logging from lite-server
:open: false
logLevel: "silent",
server: {
middleware: {
0: null
}
}
Known Issues
CSS with Angular 2 is embedded thus even though BrowserSync detects the file change to CSS, it does not inject the file via sockets. As a workaround,injectChanges
defaults to false
.Contributing
- Fork and clone it
- Install dependencies:
npm install
- Create a feature branch:
git checkout -b new-feature
- Commit changes:
git commit -am 'Added a feature'
- Run static code analysis and unit tests:
npm test
- Push to the remote branch:
git push origin new-feature
- Create a new Pull Request