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