Simple grunt task for running an Express server that works great with LiveReload + Watch/Regarde
This plugin requires Grunt ~0.4.0
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-express-server --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-express-server');
In your project's Gruntfile, you can create one or multiple servers:
grunt.initConfig({
express: {
options: {
// Override defaults here
},
dev: {
options: {
script: 'path/to/dev/server.js'
}
},
prod: {
options: {
script: 'path/to/prod/server.js',
node_env: 'production'
}
},
test: {
options: {
script: 'path/to/test/server.js'
}
}
}
});
You can override the default options
either in the root of the express
config
or within each individual server task.
express: {
options: {
// Override the command used to start the server.
// (do not use 'coffee' here, the server will not be able to restart
// see below at opts for coffee-script support)
cmd: process.argv[0],
// Will turn into: `node OPT1 OPT2 ... OPTN path/to/server.js ARG1 ARG2 ... ARGN`
// (e.g. opts: ['node_modules/coffee-script/bin/coffee'] will correctly parse coffee-script)
opts: [ ],
args: [ ],
// Setting to `false` will effectively just run `node path/to/server.js`
background: true,
// Called when the spawned server throws errors
fallback: function() {},
// Override node env's PORT
port: 3000,
// Override node env's NODE_ENV
node_env: undefined,
// Enable Node's --harmony flag
harmony: false,
// Consider the server to be "running" after an explicit delay (in milliseconds)
// (e.g. when server has no initial output)
delay: 0,
// Regular expression that matches server output to indicate it is "running"
output: ".+",
// Set --debug (true | false | integer from 1024 to 65535, has precedence over breakOnFirstLine)
debug: false,
// Set --debug-brk (true | false | integer from 1024 to 65535)
breakOnFirstLine: false,
// Object with properties `out` and `err` both will take a path to a log file and
// append the output of the server. Make sure the folders exist.
logs: undefined
}
}
By default, unless delay
or output
has been customized,
the server is considered "running" once any output is logged to the console,
upon which control is passed back to grunt.
Typically, this is:
Express server listening on port 3000
If your server doesn't log anything, the express task will never finish and none of the following tasks, after it, will be executed. For example - if you have a development task like this one:
grunt.registerTask('rebuild', ['clean', 'browserify:scripts', 'stylus', 'copy:images']);
grunt.registerTask('dev', ['rebuild', 'express', 'watch']);
If you run the dev task and your server doesn't log anything, 'watch' will never be started.
This can easily be avoided, if you log something, when server is created like that:
var server = http.createServer( app ).listen( PORT, function() {
console.log('Express server listening on port ' + PORT);
} );
If you log output before the server is running, either set delay
or output
to indicate
when the server has officially started.
If you have a server defined named dev
, you can start the server by running express:dev
. The server only runs as long as grunt is running. Once grunt's tasks have completed, the web server stops.
Similarly, if you start the dev
server with express:dev
, you can stop the server
with express:dev:stop
.
With grunt-contrib-watch
grunt.initConfig({
watch: {
express: {
files: [ '**/*.js' ],
tasks: [ 'express:dev' ],
options: {
spawn: false // for grunt-contrib-watch v0.5.0+, "nospawn: true" for lower versions. Without this option specified express won't be reloaded
}
}
}
});
grunt.registerTask('server', [ 'express:dev', 'watch' ])
Important: Note that the spawn: false
options only need be applied to the watch target regarding the express task.
You may have other watch targets that use spawn: true
, which is useful, for example, to reload CSS and not LESS changes.
watch: {
options: {
livereload: true
},
express: {
files: [ '**/*.js' ],
tasks: [ 'express:dev' ],
options: {
spawn: false
}
},
less: {
files: ["public/**/*.less"],
tasks: ["less"],
options: {
livereload: false
}
},
public: {
files: ["public/**/*.css", "public/**/*.js"]
}
}
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
- v0.5.1 - Add
harmony
flag (#86) - v0.5.0 - Add breakOnFirstLine option, support for debug ports and fix bugs. Details: (#68, #70, #73)
- v0.4.19 – Use
process.env.PORT
before3000
(#59) - v0.4.18 – Fix for when running the node debugger (#57)
- v0.4.17 – Update
devDependencies
...again - v0.4.16 – Update
devDependencies
- v0.4.15 – Recommend using local
coffee
with additional arguments (#50) - v0.4.14 – Attempt to fix issues running Coffeescript (#54)
- v0.4.13 – Add
--nodejs
for Coffeescript users (#37) - v0.4.12 – Only remove this task's listeners (#39)
- v0.4.11 – Revert v0.4.10 until Travis can reproduce it
- v0.4.10 – Another attempt to fix #28 & #30's server restarting issue (#31)
- v0.4.9 – Revert v0.4.8 until #30 is resolved
- v0.4.8 – Fix issue with start/restarting multiple instances (#29)
- v0.4.7 – Remove broken
error
option (#27) - v0.4.6 – Store running servers on
process._servers[target]
(#22) - v0.4.5 – Support multiple servers running at once (#23)
- v0.4.4 - Fix for using
grunt-env
to change environments, thanks to @FredrikAppelros (#20) - v0.4.3 - Add
cmd
option that defaults to Node, but can be set tocoffee
for Coffeescript support, thanks to @JonET (#15) - v0.4.2 - Add
debug
option that gets enables Node's debugger, ideally for use with node-inspector - v0.4.1 - Add
node_env
option that setsNODE_ENV
when running the server & restores original env upon closing, thanks to @jgable! - v0.4.0
- Add
delay
option that, when set, passes control back to grunt after timeout - Add
output
regular expression option that, when set, waits for matching message before passing control back to grunt
- Add
- v0.3.1 - Try to force notification that
express
task has finished as much as possible - v0.3.0 -
express
is now a multitask with customizable options, better error handling and:stop
task - v0.2.0
- Change
express-server
task toexpress
- Config is set via
express: '...'
instead ofserver: { script: '...' }
- Change
- v0.1.0 - Initial import from Genesis Skeleton & release