1 | gulp-live-server
|
2 | ===
|
3 |
|
4 | [![status][1]][2] [![downloads][3]][4] [![tag][5]][6] [![license][7]][8]
|
5 |
|
6 | [1]: http://img.shields.io/travis/gimm/gulp-live-server/master.svg?style=flat-square
|
7 | [2]: https://travis-ci.org/gimm/gulp-live-server
|
8 |
|
9 | [3]: http://img.shields.io/npm/dm/gulp-live-server.svg?style=flat-square
|
10 | [4]: https://www.npmjs.com/package/gulp-live-server
|
11 |
|
12 | [5]: https://img.shields.io/github/tag/gimm/gulp-live-server.svg?style=flat-square
|
13 | [6]: https://github.com/gimm/gulp-live-server/releases
|
14 |
|
15 | [7]: http://img.shields.io/badge/license-WTFPL-blue.svg?style=flat-square
|
16 | [8]: http://www.wtfpl.net
|
17 |
|
18 | A handy, light-weight server you're going to love.
|
19 |
|
20 | - [Install](#install)
|
21 | - [Usage](#usage)
|
22 | - [API](#api)
|
23 | - [static](#staticfolder-port)
|
24 | - [new](#newscript)
|
25 | - [gls](#glsargs-options-livereload)
|
26 | - [start](#start)
|
27 | - [stop](#stop)
|
28 | - [notify](#notifyevent)
|
29 | - [livereload.js](#livereloadjs)
|
30 | - [Debug](#debug)
|
31 |
|
32 | Install
|
33 | ---
|
34 | [![NPM](https://nodei.co/npm/gulp-live-server.png?compact=true)](https://nodei.co/npm/gulp-live-server/)
|
35 |
|
36 | Usage
|
37 | ---
|
38 | - Serve a static folder(`gls.script`<'scripts/static.js'> is used as server script)
|
39 |
|
40 | ```js
|
41 | var gulp = require('gulp');
|
42 | var gls = require('gulp-live-server');
|
43 | gulp.task('serve', function() {
|
44 | //1. serve with default settings
|
45 | var server = gls.static(); //equals to gls.static('public', 3000);
|
46 | server.start();
|
47 |
|
48 | //2. serve at custom port
|
49 | var server = gls.static('dist', 8888);
|
50 | server.start();
|
51 |
|
52 | //3. serve multi folders
|
53 | var server = gls.static(['dist', '.tmp']);
|
54 | server.start();
|
55 |
|
56 | //use gulp.watch to trigger server actions(notify, start or stop)
|
57 | gulp.watch(['static/**/*.css', 'static/**/*.html'], server.notify);
|
58 | });
|
59 | ```
|
60 | - Serve with your own script file
|
61 |
|
62 | ```js
|
63 | gulp.task('serve', function() {
|
64 | //1. run your script as a server
|
65 | var server = gls.new('myapp.js');
|
66 | server.start();
|
67 |
|
68 | //2. run script with cwd args, e.g. the harmony flag
|
69 | var server = gls.new(['--harmony', 'myapp.js']);
|
70 | //this will achieve `node --harmony myapp.js`
|
71 | //you can access cwd args in `myapp.js` via `process.argv`
|
72 | server.start();
|
73 |
|
74 | //use gulp.watch to trigger server actions(notify, start or stop)
|
75 | gulp.watch(['static/**/*.css', 'static/**/*.html'], server.notify);
|
76 | gulp.watch('myapp.js', server.start); //restart my server
|
77 | });
|
78 | ```
|
79 |
|
80 | - Customized serving with gls
|
81 |
|
82 | ```js
|
83 | gulp.task('serve', function() {
|
84 | //1. gls is the base for `static` and `new`
|
85 | var server = gls([gls.script, 'static', 8000]);
|
86 | //equals gls.new([gls.script, 'static', 8000]);
|
87 | //equals gls.static('static', 8000);
|
88 | server.start();
|
89 |
|
90 | //2. set running options for the server, e.g. NODE_ENV
|
91 | var server = gls('myapp.js', {env: {NODE_ENV: 'development'}});
|
92 | server.start();
|
93 |
|
94 | //3. customize livereload server, e.g. port number
|
95 | var server = gls('myapp.js', undefined, 12345);
|
96 | server.start();
|
97 |
|
98 | //use gulp.watch to trigger server actions(notify, start or stop)
|
99 | gulp.watch(['static/**/*.css', 'static/**/*.html'], server.notify);
|
100 | gulp.watch('myapp.js', server.start); //restart my server
|
101 | });
|
102 | ```
|
103 |
|
104 | API
|
105 | ---
|
106 | ### static([folder][, port])
|
107 | - `folder` - `String|Array` The folder(s) to serve.
|
108 | Use array of strings if there're multi folders to serve.
|
109 | If omitted, defaults to `public/`.
|
110 | - `port` - `Number` The port to listen on. Defaults to `3000`.
|
111 | - return [gls](#glsargs-options-livereload).
|
112 |
|
113 | Config new server using the [default server script](https://github.com/gimm/gulp-live-server/blob/master/scripts/static.js), to serve the given `folder` on the specified `port`.
|
114 |
|
115 | ### new(script)
|
116 | - `script` - `String` The script file to run.
|
117 | - return [gls](#glsargs-options-livereload).
|
118 |
|
119 | Config new server using the given `script`.
|
120 |
|
121 | ### gls(args[, options][, livereload])
|
122 | - `args` - `String|Array` The 2nd param for [ChildProcess.spawn](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).
|
123 | - `options` - `Object` The 3rd param for [ChildProcess.spawn](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options),
|
124 | will be mixin into the default value:
|
125 |
|
126 | ```js
|
127 | options = {
|
128 | cwd: undefined
|
129 | }
|
130 | options.env = process.env;
|
131 | options.env.NODE_ENV = 'development';
|
132 | ```
|
133 | - `livereload` - `Boolean|Number|Object` The option for tiny-lr server. The default value is `35729`.
|
134 | - `false` - will disable tiny-lr livereload server.
|
135 | - `number` - treated as port number of livereload server.
|
136 | - `object` - used to create tiny-lr server new tinylr.Server(livereload);
|
137 |
|
138 | **`gls` here is a reference of `var gls = require('gulp-live-server')`**. It aims to assemble configuration for the server child process as well as the tiny-lr server.
|
139 | **`static` and `new` are just shortcuts for this.**
|
140 | Usually, `static` and `new` will serve you well, but you can get more customized server with `gls`.
|
141 |
|
142 | ### start()
|
143 | - return [promise](https://github.com/kriskowal/q/wiki/API-Reference) from [Q](https://www.npmjs.com/package/q)
|
144 |
|
145 | Spawn a new child process based on the configuration.
|
146 | - use [`ChildProcess.spawn`](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) to start a node process;
|
147 | - use [`tiny-lr`](https://github.com/mklabs/tiny-lr) provide livereload ability;
|
148 |
|
149 | ### stop()
|
150 | - return [promise](https://github.com/kriskowal/q/wiki/API-Reference) from [Q](https://www.npmjs.com/package/q)
|
151 |
|
152 | Stop the server.
|
153 |
|
154 | ### notify([event])
|
155 | - `event` - `Event` Event object passed along with [gulp.watch](https://github.com/gulpjs/gulp/blob/master/docs/API.md#cbevent).
|
156 | Optional when used with `pipe`.
|
157 |
|
158 | Tell livereload.js to reload the changed resource(s)
|
159 |
|
160 | livereload.js
|
161 | ---
|
162 | glup-live-server comes with [tiny-lr](https://github.com/mklabs/tiny-lr/) built in, which works as a livereload server. `livereload.js` is **served** by `tiny-lr`, but in order to get it loaded with your page, you have 3 options( to **inject** `<script src="//localhost:35729/livereload.js"></script>` into your page):
|
163 | - [LiveReload](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?hl=en) for Chrome;
|
164 | - Use [connect-livereload](https://github.com/intesso/connect-livereload) middleware;
|
165 | - Add [livereload.js](https://github.com/livereload/livereload-js) in your page mannully;
|
166 |
|
167 | Usually, if `http://livereload:35729/livereload.js` is accessible, then your livereload server is ok, if you don't have the script tag for livereload.js in you page, you've problem with either your chrome plugin or the connect-livereload middle-ware as mentioned above.
|
168 |
|
169 | DEBUG
|
170 | ---
|
171 | If you want more output, set the `DEBUG` environment variables to `*` or `gulp-live-server`.
|