Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 254 lines (146 sloc) 11.409 kB
90666b0 @remy Update nodemon logo (to svg)
authored
1 ![nodemon logo](http://nodemon.io/nodemon.svg)
d99b3ed @remy Gimme a logo
authored
2
580648c @remy first commit
authored
3 # nodemon
4
537d6dc @remy flattr badge
authored
5 [![Flattr this](http://api.flattr.com/button/flattr-badge-large.png)](http://flattr.com/thing/1211372/remynodemon-on-GitHub)
3cdd2d3 @remy status badges
authored
6
4785409 @remy tweaks to copy
authored
7 For use during development of a node.js based application.
580648c @remy first commit
authored
8
8589fab @rmi22186 Update README.md
rmi22186 authored
9 nodemon will watch the files in the directory in which nodemon was started, and if any files change, nodemon will automatically restart your node application.
580648c @remy first commit
authored
10
8b5f1e3 @remy directions on using nodemon with forever
authored
11 nodemon does **not** require *any* changes to your code or method of development. nodemon simply wraps your node application and keeps an eye on any files that have changed. Remember that nodemon is a replacement wrapper for `node`, think of it as replacing the word "node" on the command line when you run your script.
580648c @remy first commit
authored
12
d939f64 @remy Link to npm
authored
13 [![NPM version](https://badge.fury.io/js/nodemon.svg)](https://npmjs.org/package/nodemon)
7b04236 @remy Update Travis badge based on master
authored
14 [![Travis Status](https://travis-ci.org/remy/nodemon.svg?branch=master)](https://travis-ci.org/remy/nodemon)
537d6dc @remy flattr badge
authored
15
c0b3776 @remy add npm install notes
authored
16 # Installation
17
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
18 Either through forking or by using [npm](http://npmjs.org) (the recommended way):
c0b3776 @remy add npm install notes
authored
19
6cb721a @remy Update README.md
authored
20 npm install -g nodemon
8ca0264 @remy Support manual restart using "rs" command. Fixes #162
authored
21
8b5f1e3 @remy directions on using nodemon with forever
authored
22 And nodemon will be installed in to your bin path. Note that as of npm v1, you must explicitly tell npm to install globally as nodemon is a command line utility.
c0b3776 @remy add npm install notes
authored
23
580648c @remy first commit
authored
24 # Usage
25
8b5f1e3 @remy directions on using nodemon with forever
authored
26 nodemon wraps your application, so you can pass all the arguments you would normally pass to your app:
580648c @remy first commit
authored
27
28 nodemon [your node app]
88269ba @remy Automatically tests for package.json file - Closes #14, and support f…
authored
29
3ccbd23 @remy Show -h option
authored
30 For CLI options, use the `-h` (or `--help`) argument:
31
32 nodemon -h
33
34 Using nodemon is simple, if my application accepted a host and port as the arguments, I would start it as so:
580648c @remy first commit
authored
35
36 nodemon ./server.js localhost 8080
37
38 Any output from this script is prefixed with `[nodemon]`, otherwise all output from your application, errors included, will be echoed out as expected.
39
82ae44c @mortonfox Fix CoffeeScript link.
mortonfox authored
40 nodemon also supports running and monitoring [coffee-script](http://coffeescript.org/) apps:
88269ba @remy Automatically tests for package.json file - Closes #14, and support f…
authored
41
42 nodemon server.coffee
43
8b5f1e3 @remy directions on using nodemon with forever
authored
44 If no script is given, nodemon will test for a `package.json` file and if found, will run the file associated with the *main* property ([ref](https://github.com/remy/nodemon/issues/14)).
88269ba @remy Automatically tests for package.json file - Closes #14, and support f…
authored
45
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
46 You can also pass the debug flag to node through the command line as you would normally:
47
48 nodemon --debug ./server.js 80
49
8b5f1e3 @remy directions on using nodemon with forever
authored
50 If you have a `package.json` file for your app, you can omit the main script entirely and nodemon will read the `package.json` for the `main` property and use that value as the app.
d2415d9 @remy updated readme with some of the new features
authored
51
c4a7e07 @remy Adding support for package.scripts.start
authored
52 nodemon will also search for the `scripts.start` property in `package.json` (as of nodemon 1.1.x).
53
93ab2b0 @remy Updating FAQ & authors
authored
54 Also check out the [FAQ](https://github.com/remy/nodemon/blob/master/faq.md) or [issues](https://github.com/remy/nodemon/issues) for nodemon.
55
56 ## Automatic re-running
d2415d9 @remy updated readme with some of the new features
authored
57
2d62055 @brianjscoles fix typo in README.md
brianjscoles authored
58 nodemon was originally written to restart hanging processes such as web servers, but now supports apps that cleanly exit. If your script exits cleanly, nodemon will continue to monitor the directory (or directories) and restart the script if there are any changes.
d2415d9 @remy updated readme with some of the new features
authored
59
93ab2b0 @remy Updating FAQ & authors
authored
60 ## Manual restarting
8ca0264 @remy Support manual restart using "rs" command. Fixes #162
authored
61
5b74ab5 @didoarellano Fix typos
didoarellano authored
62 Whilst nodemon is running, if you need to manually restart your application, instead of stopping and restart nodemon, you can simply type `rs` with a carriage return, and nodemon will restart your process.
8ca0264 @remy Support manual restart using "rs" command. Fixes #162
authored
63
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
64 ## Config files
65
66 nodemon supports local and global configuration files. These are named `nodemon.json` and can be located in the current working directory or in your home directory.
67
68 The specificity is as follows, so that a command line argument will always override the config file settings:
69
70 - command line arguments
71 - local config
72 - global config
73
74 A config file can take any of the command line arguments as JSON key values, for example:
75
76 {
77 "verbose": true,
0793386 @arielyang Missing a comma.
arielyang authored
78 "ignore": ["*.test.js", "fixtures/*"],
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
79 "execMap": {
80 "rb": "ruby",
81 "pde": "processing --sketch={{pwd}} --run"
82 }
83 }
84
85 The above `nodemon.json` file might be my global config so that I have support for ruby files and processing files, and I can simply run `nodemon demo.pde` and nodemon will automatically know how to run the script even though out of the box support for processing scripts.
86
c78bcb9 @remy Documentation of required nodemon
authored
87 A further example of options can be seen in [sample-nodemon.md](https://github.com/remy/nodemon/blob/master/doc/sample-nodemon.md)
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
88
c78bcb9 @remy Documentation of required nodemon
authored
89 *This section needs better documentation, but for now you can also see `nodemon --help config` ([also here](https://github.com/remy/nodemon/blob/master/doc/cli/config.txt))*.
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
90
0945ee9 @remy merge fixes
authored
91 ## Using nodemon as a module
92
93 Please see [doc/requireable.md](doc/requireable.md)
94
93ab2b0 @remy Updating FAQ & authors
authored
95 ## Running non-node scripts
d2415d9 @remy updated readme with some of the new features
authored
96
8b5f1e3 @remy directions on using nodemon with forever
authored
97 nodemon can also be used to execute and monitor other programs. nodemon will read the file extension of the script being run and monitor that extension instead of .js if there's no .nodemonignore:
d2415d9 @remy updated readme with some of the new features
authored
98
e299e56 @remy fixed param parsing and now reading correctly exec args - ideally quo…
authored
99 nodemon --exec "python -v" ./app.py
d2415d9 @remy updated readme with some of the new features
authored
100
e299e56 @remy fixed param parsing and now reading correctly exec args - ideally quo…
authored
101 Now nodemon will run `app.py` with python in verbose mode (note that if you're not passing args to the exec program, you don't need the quotes), and look for new or modified files with the `.py` extension.
d2415d9 @remy updated readme with some of the new features
authored
102
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
103 ### Default executables
104
105 Using the `nodemon.json` config file, you can define your own default executables using the `execMap` property. This is particularly useful if you're working with a language that isn't supported by default by nodemon.
106
107 To add support for nodemon to know about the .pl extension (for Perl), the nodemon.json file would add:
108
109 {
110 "execMap": {
111 "pl": "perl"
112 }
113 }
114
115 Now running the following, nodemon will know to use `perl` as the executable:
116
117 nodemon script.pl
118
b7bb663 @remy Link to defaults.js
authored
119 It's generally recommended to use the global `nodemon.json` to add your own `execMap` options. However, if there's a common default that's missing, this can be merged in to the project so that nodemon supports it by default, by changing [default.js](https://github.com/remy/nodemon/blob/master/lib/config/defaults.js) and sending a pull request.
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
120
93ab2b0 @remy Updating FAQ & authors
authored
121 ## Monitoring multiple directories
d2415d9 @remy updated readme with some of the new features
authored
122
8b5f1e3 @remy directions on using nodemon with forever
authored
123 By default nodemon monitors the current working directory. If you want to take control of that option, use the `--watch` option to add specific paths:
d2415d9 @remy updated readme with some of the new features
authored
124
125 nodemon --watch app --watch libs app/server.js
126
8b5f1e3 @remy directions on using nodemon with forever
authored
127 Now nodemon will only restart if there are changes in the `./app` or `./libs` directory. By default nodemon will traverse sub-directories, so there's no need in explicitly including sub-directories.
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
128
93ab2b0 @remy Updating FAQ & authors
authored
129 ## Specifying extension watch list
ac9a6c7 @remy Update README.md
authored
130
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
131 By default, nodemon looks for files with the `.js`, `.coffee`, and `.litcoffee` extensions. If you use the `--exec` option and monitor `app.py` nodemon will monitor files with the extension of `.py`. However, you can specify your own list with the `-e` (or `--ext`) switch like so:
ac9a6c7 @remy Update README.md
authored
132
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
133 nodemon -e js,jade
8ca0264 @remy Support manual restart using "rs" command. Fixes #162
authored
134
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
135 Now nodemon will restart on any changes to files in the directory (or subdirectories) with the extensions .js, .jade.
ac9a6c7 @remy Update README.md
authored
136
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
137 ## Ignoring files
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
138
5b74ab5 @didoarellano Fix typos
didoarellano authored
139 By default, nodemon will only restart when a `.js` JavaScript file changes. In some cases you will want to ignore some specific files, directories or file patterns, to prevent nodemon from prematurely restarting your application.
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
140
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
141 This can be done via the command line:
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
142
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
143 nodemon --ignore lib/ --ignore tests/
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
144
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
145 Or specific files can be ignored:
7e3a9e6 @remy Fixing constant restart by removing and chmod'ing monitor file (Close…
authored
146
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
147 nodemon --ignore lib/app.js
580648c @remy first commit
authored
148
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
149 Patterns can also be ignored (but be sure to quote the arguments):
580648c @remy first commit
authored
150
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
151 nodemon --ignore 'lib/*.js'
580648c @remy first commit
authored
152
c4a7e07 @remy Adding support for package.scripts.start
authored
153 Note that by default, nodemon will ignore the `.git`, `node_modules`, `bower_components` and `.sass-cache` directories.
580648c @remy first commit
authored
154
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
155 ## Delaying restarting
156
5b74ab5 @didoarellano Fix typos
didoarellano authored
157 In some situations, you may want to wait until a number of files have changed. The timeout before checking for new file changes is 1 second. If you're uploading a number of files and it's taking some number of seconds, this could cause your app to restart multiple times unnecessarily.
30a4a19 @remy Docs and 1.0.0 release. Whoop whoop!
authored
158
159 To add an extra throttle, or delay restarting, use the `--delay` command:
160
161 nodemon --delay 10 server.js
4208c11 @remy details on how to handle your own shutdown
authored
162
d96f117 Document the milliseconds support for --delay option
Justin G authored
163 For more precision, milliseconds can be specified. Either as a float:
164
165 nodemon --delay 2.5 server.js
166
167 Or using the time specifier (ms):
168
169 nodemon --delay 2500ms server.js
170
171 The delay figure is number of seconds (or milliseconds, if specified) to delay before restarting. So nodemon will only restart your app the given number of seconds after the *last* file change.
e71aac2 @remy Clarified where nodemonignore is read from. Fixes #75
authored
172
93ab2b0 @remy Updating FAQ & authors
authored
173 ## Controlling shutdown of your script
4208c11 @remy details on how to handle your own shutdown
authored
174
8b5f1e3 @remy directions on using nodemon with forever
authored
175 nodemon sends a kill signal to your application when it sees a file update. If you need to clean up on shutdown inside your script you can capture the kill signal and handle it yourself.
4208c11 @remy details on how to handle your own shutdown
authored
176
8b5f1e3 @remy directions on using nodemon with forever
authored
177 The following example will listen once for the `SIGUSR2` signal (used by nodemon to restart), run the clean up process and then kill itself for nodemon to continue control:
4208c11 @remy details on how to handle your own shutdown
authored
178
179 process.once('SIGUSR2', function () {
180 gracefulShutdown(function () {
4785409 @remy tweaks to copy
authored
181 process.kill(process.pid, 'SIGUSR2');
5b74ab5 @didoarellano Fix typos
didoarellano authored
182 });
4208c11 @remy details on how to handle your own shutdown
authored
183 });
184
d4908f6 @mikemaccana Add gulp-nodemon link. Also correct small typo.
mikemaccana authored
185 Note that the `process.kill` is *only* called once your shutdown jobs are complete. Hat tip to [Benjie Gillam](http://www.benjiegillam.com/2011/08/node-js-clean-restart-and-faster-development-with-nodemon/) for writing this technique up.
186
1cafc64 @remy Fixed #470
authored
187 ## Triggering events when nodemon state changes
188
189 If you want growl like notifications when nodemon restarts or to trigger an action when an event happens, then you can either `require` nodemon or simply add event actions to your `nodemon.json` file.
190
191 For example, to trigger a notification on a Mac when nodemon restarts, `nodemon.json` looks like this:
192
193 ```json
194 {
195 "events": {
196 "restart": "osascript -e 'display notification \"app restarted\" with title \"nodemon\"'"
197 }
198 }
199 ```
200
201 A full list of available events is listed on the [event states wiki](https://github.com/remy/nodemon/wiki/Events#states). Note that you can bind to both states and messages.
202
c4e263e @binarykitchen expose streams for piping (mh)
binarykitchen authored
203 ## Pipe output to somewhere else
204
205 ```js
e872aff @remy Tweak to spaces and code examples
authored
206 nodemon({
207 script: ...,
208 stdout: false // important: this tells nodemon not to output to console
209 }).on('readable', function() { // the `readable` event indicates that data is ready to pick up
210 this.stdout.pipe(fs.createWriteStream('output.txt'));
211 this.stderr.pipe(fs.createWriteStream('err.txt'));
212 });
c4e263e @binarykitchen expose streams for piping (mh)
binarykitchen authored
213 ```
214
f4469e1 @remy Show how to use iojs with nodemon
authored
215 ## Using io.js for nodemon
216
cf134e5 @remy Updated note about iojs
authored
217 If you *only* have io.js installed (and the default install creates a symlink from `node` to `iojs`), then nodemon will work just fine out of the box (or [should](https://github.com/remy/nodemon/issues/468)).
218
219 If you've got *both* node and io.js installed, then it's easy! You can either edit the local `nodemon.json` file (in your working directory) or in your `$HOME` directory containing:
f4469e1 @remy Show how to use iojs with nodemon
authored
220
221 ```json
222 {
223 "execMap": {
224 "js": "iojs"
225 }
226 }
227 ```
228
229 Now you nodemon will use [io.js](https://iojs.org/) with JavaScript files instead of node.
230
d4908f6 @mikemaccana Add gulp-nodemon link. Also correct small typo.
mikemaccana authored
231 ## Using nodemon in your gulp workflow
232
233 Check out the [gulp-nodemon](https://github.com/JacksonGariety/gulp-nodemon) plugin to integrate nodemon with the rest of your project's gulp workflow.
8b5f1e3 @remy directions on using nodemon with forever
authored
234
93ab2b0 @remy Updating FAQ & authors
authored
235 ## Using nodemon in your Grunt workflow
04526d3 @remy Tweak to readme
authored
236
994b2b5 @ChrisWren added mention of grunt-nodemon in README
ChrisWren authored
237 Check out the [grunt-nodemon](https://github.com/ChrisWren/grunt-nodemon) plugin to integrate nodemon with the rest of your project's grunt workflow.
238
dd6ad0d @remy Pronunciation
authored
239 ## Pronunciation
240
241 > nodemon, is it pronunced: node-mon, no-demon or node-e-mon (like pokémon)?
242
243 Well...I've been asked this many times before. I like that I've been asked this before. There's been bets as to which one it actually is.
244
245 The answer is simple, but possibly frustrating. I'm not saying (how I pronounce it). It's up to you to call it as you like. All answers are correct :)
246
542f854 @remy Fixed #457
authored
247 ## FAQ
248
249 See the [FAQ](https://github.com/remy/nodemon/blob/master/faq.md) and please add your own questions if you think they would help others.
250
00995f8 @remy +license in package
authored
251 # License
252
d939f64 @remy Link to npm
authored
253 MIT [http://rem.mit-license.org](http://rem.mit-license.org)
Something went wrong with that request. Please try again.