npm 中文文档

lite-server


Lightweight development onlynode 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:

  1. ``` shell
  2. npm install lite-server --save-dev
  3. yarn add lite-server --dev # or yarn
  4. ```...and add a "script" entry within your project's `package.json` file:

  1. ``` json
  2. # Inside package.json...
  3.   "scripts": {
  4.     "dev": "lite-server"
  5.   },
  6. ```

With the above script entry, you can then start lite-server via:

  1. ``` shell
  2. npm run dev
  3. ```

Other options for running locally installed NPM binaries is discussed in this Stack Overflow question: How to use package installed locally in node_modules

Using on the fly


lite-server can be used with npx

  1. ``` shell
  2. npx lite-server
  3. ```

Global Installation


lite-server can be also installed globally, if preferred:

  1. ``` shell
  2. npm install --global lite-server

  4. # To run:
  5. lite-server
  6. ```

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:

  1. ``` shell
  2. lite-server -c configs/my-bs-config.js
  3. ```

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:

  1. ``` json
  2. {
  3.   "port": 8000,
  4.   "files": ["./src/**/*.{html,htm,css,js}"],
  5.   "server": { "baseDir": "./src" }
  6. }
  7. ```

You can also provide custom path to your base directory --baseDir= run time options:

  1. ``` shell
  2. lite-server --baseDir="dist"
  3. ```

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:

  1. ``` js
  2. module.exports = {
  3.   server: {
  4.     middleware: {
  5.       // overrides the second middleware default with new settings
  6.       1: require('connect-history-api-fallback')({
  7.         index: '/index.html',
  8.         verbose: true,
  9.       }),
  10.     },
  11.   },
  12. };
  13. ```

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.

  1. ``` js
  2. module.exports = function (bs) {
  3.   return {
  4.     server: {
  5.       middleware: {
  6.         // overrides the second middleware default with new settings
  7.         1: require('connect-history-api-fallback')({
  8.           index: '/index.html',
  9.           verbose: true,
  10.         }),
  11.       },
  12.     },
  13.   };
  14. };
  15. ```

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:

  1. ``` shell
  2. npm install connect-history-api-fallback --save-dev
  3. ```...otherwise you'll get an error similar to:

  1. ``` shell
  2. Error: Cannot find module 'connect-history-api-fallback'
  3. ```

Another example: To remove one of the default middlewares, such as connect-logger, you can set it's array index to null :

  1. ``` js
  2. module.exports = {
  3.   server: {
  4.     middleware: {
  5.       0: null, // removes default `connect-logger` middleware
  6.     },
  7.   },
  8. };
  9. ```

A list of the entire set of BrowserSync options can be found in its docs: http://www.browsersync.io/docs/options/

Testing


When using lite-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 :

  1. ``` js
  2.   open: false
  3.   logLevel: "silent",
  4.   server: {
  5.     middleware: {
  6.       0: null
  7.     }
  8.   }
  9. ```

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

License


Code released under the MIT license.