https://github.com/devpaul/grunt-devserver
A simple development web server that serves static content from a directory
https://github.com/devpaul/grunt-devserver
Last synced: about 1 year ago
JSON representation
A simple development web server that serves static content from a directory
- Host: GitHub
- URL: https://github.com/devpaul/grunt-devserver
- Owner: devpaul
- License: mit
- Created: 2012-11-30T19:02:31.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2016-02-20T21:39:22.000Z (over 10 years ago)
- Last Synced: 2025-04-12T18:12:51.876Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 778 KB
- Stars: 14
- Watchers: 1
- Forks: 3
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: license.txt
Awesome Lists containing this project
README
# Developer Web Server
grunt-devserver provides a simple way to quickly get a development server serving up your content with
* run from the command line or Grunt 0.4.x
* no caching content
* CORS headers for cross-domain requests
* logs requests to console
* quickly configure https server
* redefine your middleware in configuration
As a developer I needed a lightweight way to serve up client-side applications and content in isolation from a larger
server application. Something that supported a rapid workflow and integrated with my tools.
[](https://travis-ci.org/devpaul/grunt-devserver) [](http://badge.fury.io/js/grunt-devserver)
## Installation
Install it from the command line into your project
```
npm install grunt-devserver --save-dev
```
Or install it globally
```
npm install grunt-devserver -g
```
## Usage
### From the Command Line
Once grunt-devserver has been installed globally you can run it from any folder by typing `devserver`
Command line options:
```
-t, --type (server type) http|https (default is http)
-p, --port (port number) listen on this port
-f, --folder (full path to a folder) serves this folder
-s, --server start a server as defined in the configuration
--cache (method) the method to return in the Cache-Control HTTP header. Default is no-cache.
--file (filename) loads a js/json configuration file
```
For more information on configuration files see [Configuration Files](#configuration)
### From Grunt
To start a server through grunt you need a devserver configuration in your `Gruntfile.js` and tell
grunt to load `grunt-devserver` as an available task. For more information see [Configuring Tasks][Grunt Config].
```
var config = {devserver: {server: {}}}
grunt.initConfig(config)
grunt.loadNpmTasks('grunt-devserver')
```
and execute using:
```
grunt devserver
```
Now you can add the following options:
```
devserver: { options: { 'type' : (http|https defaults to http)
, 'port' : (defaults to 8888)
, 'base' : (defaults to .)
, 'cache' : (defaults to 'no-cache')
, 'httpsOptions' : https.createServer options
, 'file' :
, 'async' : (defaults to true)
, 'middleware' : || (defaults to predefined middleware)
}
}
```
NOTE: Starting multiple devservers requires setting the `async` option to false so that other server tasks may be
processed. `async` can also be useful when a server is needed to support integration or functional testing.
See the [Configuration](#configuration) section for more information.
### From Your Project
You can also use devserver directly as a module in your project.
```
var devserver = require('grunt-devserver')
, options = { type: "http", port: 8000 }
, serverStarted = devserver(options)
serverStarted.then(function(server) {
// TODO something awesome
})
```
### From WebStorm
As a developer tool integration is extremely important. If you are using a Jetbrains IDE like WebStorm
here are instructions to start a devserver directly in your IDE by adding an entry to your
[External Tools][jbExternalTools]:
1. Go to Preferences > External Tools
1. Click Add
1. Fill in the form:
1. name: http
1. group: devserver
1. program: /usr/local/bin/devserver
1. paramters: --port $Prompt$
1. working directory: $FileDir$
1. Hit OK. You should now be able to right-click on any folder and start your devserver!
#### Troubleshooting
*Q*: I am getting "`env: node: No such file or directory`"
You need to add node to your path. On a Mac 10.8.x or later [see launchctl man page][launchctl]
for more information.
1. From a terminal run ` sudo vim /etc/launchd.conf `
1. Add ` setenv PATH /usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin `
1. Reboot
## Configuration
Configuration files provide you with the same functionality as a grunt configuration and can easily be shared across
projects or used from the command-line.
### Options
#### type
The type of server
Type: `string`
Default: `http`
Command line: `-t, --type`
#### port
The port where the server will respond
type: `number`
default: `8888`
command line: `-p, --port`
#### base
The base directory of the web server. This is where files will be served. This configuration is passed to the
`serve-index` middleware.
type: `String`
default: `'.'`
command line: `-f, --folder`
#### cache
The type of caching mechanism to use. The `noCacheHeaders` middleware uses this value to add `Cache-Control`
headers to the HTTP response.
type: `String`
default: `no-cache`
command line: `--cache`
#### httpsOptions
`httpsOptions` are passed directly through to node's https.createServer() method. [Read the docs for more information][nodehttps].
This is ignored unless the server type is specified as `https`. When a signing certificate is not present, one will be
automatically generated.
type: `object`
default: none
#### file
As external configuration file. See [Using Configuration Files](#configuration) for samples on how to use file
configurations with devserver
type: `string`
default: none
command line: `--file`
#### async
`async` if set to true it will keep Grunt from terminating (see [Grunt Tasks])
type: `boolean`
default: `true`
#### middleware
Redefines the middleware stack to be used by the server.
type: `array` or `function`
default: @see `model/CommonConfig.defaultMiddleware`
Example: redefine the middleware to log the request and send a hello world message
```
{ options: { middleware: [ morgan()
, function(req, res, next) {
res.send('Hello world!').end(200)
}
]
}
}
```
Routes can also be used to define specific middleware handlers
```
var route = require('devserver').middleware.route
var morgan = require('morgan')
function getName(req, res, next) {
// retrieve the user name
}
function putName(req, res, next) {
// update the user name
}
{ options: { middleware: [ morgan()
, route('/name/:id').get(getName).put(putName)
]
}
}
```
### Option Precedence
When a property exists in the grunt/command-line configuration and in the configuration file, the grunt/command-line
option always overrides the file options.
### Example
A example devserverrc file
```
{ "options": { "type" : "http"
, "port" : 8888
}
}
```
When this file is loaded from the command-line
```
devserver --file "./devserverrc" --port 4321 --cache "no-store"
```
The resulting configuration used by devserver
```
{ "options": { "type" : "http"
, "port" : 4321
, "cache" : "no-store"
}
}
```
[nodehttps]: http://nodejs.org/api/https.html#https_https_createserver_options_requestlistener
[launchctl]: http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/launchctl.1.html
[jbExternalTools]: http://www.jetbrains.com/idea/webhelp/external-tools.html
[Grunt]: http://www.gruntjs.com
[Grunt Tasks]: http://gruntjs.com/api/inside-tasks#this.async
[Grunt Config]: http://gruntjs.com/configuring-tasks