dgbuilder/dgeflows/node_modules/express/node_modules/serve-static/README.md

   1 # serve-static
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Linux Build][travis-image]][travis-url]
   6 [![Windows Build][appveyor-image]][appveyor-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8 [![Gratipay][gratipay-image]][gratipay-url]
   9
  10 ## Install
  11
  12 ```sh
  13 $ npm install serve-static
  14 ```
  15
  16 ## API
  17
  18 ```js
  19 var serveStatic = require('serve-static')
  20 ```
  21
  22 ### serveStatic(root, options)
  23
  24 Create a new middleware function to serve files from within a given root
  25 directory. The file to serve will be determined by combining `req.url`
  26 with the provided root directory. When a file is not found, instead of
  27 sending a 404 response, this module will instead call `next()` to move on
  28 to the next middleware, allowing for stacking and fall-backs.
  29
  30 #### Options
  31
  32 ##### dotfiles
  33
  34  Set how "dotfiles" are treated when encountered. A dotfile is a file
  35 or directory that begins with a dot ("."). Note this check is done on
  36 the path itself without checking if the path actually exists on the
  37 disk. If `root` is specified, only the dotfiles above the root are
  38 checked (i.e. the root itself can be within a dotfile when set
  39 to "deny").
  40
  41 The default value is `'ignore'`.
  42
  43   - `'allow'` No special treatment for dotfiles.
  44   - `'deny'` Send a 403 for any request for a dotfile.
  45   - `'ignore'` Pretend like the dotfile does not exist and call `next()`.
  46
  47 ##### etag
  48
  49 Enable or disable etag generation, defaults to true.
  50
  51 ##### extensions
  52
  53 Set file extension fallbacks. When set, if a file is not found, the given
  54 extensions will be added to the file name and search for. The first that
  55 exists will be served. Example: `['html', 'htm']`.
  56
  57 The default value is `false`.
  58
  59 ##### index
  60
  61 By default this module will send "index.html" files in response to a request
  62 on a directory. To disable this set `false` or to supply a new index pass a
  63 string or an array in preferred order.
  64
  65 ##### lastModified
  66
  67 Enable or disable `Last-Modified` header, defaults to true. Uses the file
  68 system's last modified value.
  69
  70 ##### maxAge
  71
  72 Provide a max-age in milliseconds for http caching, defaults to 0. This
  73 can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
  74 module.
  75
  76 ##### redirect
  77
  78 Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.
  79
  80 ##### setHeaders
  81
  82 Function to set custom headers on response. Alterations to the headers need to
  83 occur synchronously. The function is called as `fn(res, path, stat)`, where
  84 the arguments are:
  85
  86   - `res` the response object
  87   - `path` the file path that is being sent
  88   - `stat` the stat object of the file that is being sent
  89
  90 ## Examples
  91
  92 ### Serve files with vanilla node.js http server
  93
  94 ```js
  95 var finalhandler = require('finalhandler')
  96 var http = require('http')
  97 var serveStatic = require('serve-static')
  98
  99 // Serve up public/ftp folder
 100 var serve = serveStatic('public/ftp', {'index': ['index.html', 'index.htm']})
 101
 102 // Create server
 103 var server = http.createServer(function(req, res){
 104   var done = finalhandler(req, res)
 105   serve(req, res, done)
 106 })
 107
 108 // Listen
 109 server.listen(3000)
 110 ```
 111
 112 ### Serve all files as downloads
 113
 114 ```js
 115 var contentDisposition = require('content-disposition')
 116 var finalhandler = require('finalhandler')
 117 var http = require('http')
 118 var serveStatic = require('serve-static')
 119
 120 // Serve up public/ftp folder
 121 var serve = serveStatic('public/ftp', {
 122   'index': false,
 123   'setHeaders': setHeaders
 124 })
 125
 126 // Set header to force download
 127 function setHeaders(res, path) {
 128   res.setHeader('Content-Disposition', contentDisposition(path))
 129 }
 130
 131 // Create server
 132 var server = http.createServer(function(req, res){
 133   var done = finalhandler(req, res)
 134   serve(req, res, done)
 135 })
 136
 137 // Listen
 138 server.listen(3000)
 139 ```
 140
 141 ### Serving using express
 142
 143 ```js
 144 var connect = require('connect')
 145 var serveStatic = require('serve-static')
 146
 147 var app = connect()
 148
 149 app.use(serveStatic('public/ftp', {'index': ['default.html', 'default.htm']}))
 150 app.listen(3000)
 151 ```
 152
 153 ## License
 154
 155 [MIT](LICENSE)
 156
 157 [npm-image]: https://img.shields.io/npm/v/serve-static.svg?style=flat
 158 [npm-url]: https://npmjs.org/package/serve-static
 159 [travis-image]: https://img.shields.io/travis/expressjs/serve-static/master.svg?label=linux&style=flat
 160 [travis-url]: https://travis-ci.org/expressjs/serve-static
 161 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-static/master.svg?label=windows&style=flat
 162 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-static
 163 [coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-static/master.svg?style=flat
 164 [coveralls-url]: https://coveralls.io/r/expressjs/serve-static
 165 [downloads-image]: https://img.shields.io/npm/dm/serve-static.svg?style=flat
 166 [downloads-url]: https://npmjs.org/package/serve-static
 167 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg?style=flat
 168 [gratipay-url]: https://gratipay.com/dougwilson/