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
   9 ## Install
  10
  11 This is a [Node.js](https://nodejs.org/en/) module available through the
  12 [npm registry](https://www.npmjs.com/). Installation is done using the
  13 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  14
  15 ```sh
  16 $ npm install serve-static
  17 ```
  18
  19 ## API
  20
  21 <!-- eslint-disable no-unused-vars -->
  22
  23 ```js
  24 var serveStatic = require('serve-static')
  25 ```
  26
  27 ### serveStatic(root, options)
  28
  29 Create a new middleware function to serve files from within a given root
  30 directory. The file to serve will be determined by combining `req.url`
  31 with the provided root directory. When a file is not found, instead of
  32 sending a 404 response, this module will instead call `next()` to move on
  33 to the next middleware, allowing for stacking and fall-backs.
  34
  35 #### Options
  36
  37 ##### acceptRanges
  38
  39 Enable or disable accepting ranged requests, defaults to true.
  40 Disabling this will not send `Accept-Ranges` and ignore the contents
  41 of the `Range` request header.
  42
  43 ##### cacheControl
  44
  45 Enable or disable setting `Cache-Control` response header, defaults to
  46 true. Disabling this will ignore the `immutable` and `maxAge` options.
  47
  48 ##### dotfiles
  49
  50  Set how "dotfiles" are treated when encountered. A dotfile is a file
  51 or directory that begins with a dot ("."). Note this check is done on
  52 the path itself without checking if the path actually exists on the
  53 disk. If `root` is specified, only the dotfiles above the root are
  54 checked (i.e. the root itself can be within a dotfile when set
  55 to "deny").
  56
  57   - `'allow'` No special treatment for dotfiles.
  58   - `'deny'` Deny a request for a dotfile and 403/`next()`.
  59   - `'ignore'` Pretend like the dotfile does not exist and 404/`next()`.
  60
  61 The default value is similar to `'ignore'`, with the exception that this
  62 default will not ignore the files within a directory that begins with a dot.
  63
  64 ##### etag
  65
  66 Enable or disable etag generation, defaults to true.
  67
  68 ##### extensions
  69
  70 Set file extension fallbacks. When set, if a file is not found, the given
  71 extensions will be added to the file name and search for. The first that
  72 exists will be served. Example: `['html', 'htm']`.
  73
  74 The default value is `false`.
  75
  76 ##### fallthrough
  77
  78 Set the middleware to have client errors fall-through as just unhandled
  79 requests, otherwise forward a client error. The difference is that client
  80 errors like a bad request or a request to a non-existent file will cause
  81 this middleware to simply `next()` to your next middleware when this value
  82 is `true`. When this value is `false`, these errors (even 404s), will invoke
  83 `next(err)`.
  84
  85 Typically `true` is desired such that multiple physical directories can be
  86 mapped to the same web address or for routes to fill in non-existent files.
  87
  88 The value `false` can be used if this middleware is mounted at a path that
  89 is designed to be strictly a single file system directory, which allows for
  90 short-circuiting 404s for less overhead. This middleware will also reply to
  91 all methods.
  92
  93 The default value is `true`.
  94
  95 ##### immutable
  96
  97 Enable or disable the `immutable` directive in the `Cache-Control` response
  98 header, defaults to `false`. If set to `true`, the `maxAge` option should
  99 also be specified to enable caching. The `immutable` directive will prevent
 100 supported clients from making conditional requests during the life of the
 101 `maxAge` option to check if the file has changed.
 102
 103 ##### index
 104
 105 By default this module will send "index.html" files in response to a request
 106 on a directory. To disable this set `false` or to supply a new index pass a
 107 string or an array in preferred order.
 108
 109 ##### lastModified
 110
 111 Enable or disable `Last-Modified` header, defaults to true. Uses the file
 112 system's last modified value.
 113
 114 ##### maxAge
 115
 116 Provide a max-age in milliseconds for http caching, defaults to 0. This
 117 can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
 118 module.
 119
 120 ##### redirect
 121
 122 Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.
 123
 124 ##### setHeaders
 125
 126 Function to set custom headers on response. Alterations to the headers need to
 127 occur synchronously. The function is called as `fn(res, path, stat)`, where
 128 the arguments are:
 129
 130   - `res` the response object
 131   - `path` the file path that is being sent
 132   - `stat` the stat object of the file that is being sent
 133
 134 ## Examples
 135
 136 ### Serve files with vanilla node.js http server
 137
 138 ```js
 139 var finalhandler = require('finalhandler')
 140 var http = require('http')
 141 var serveStatic = require('serve-static')
 142
 143 // Serve up public/ftp folder
 144 var serve = serveStatic('public/ftp', {'index': ['index.html', 'index.htm']})
 145
 146 // Create server
 147 var server = http.createServer(function onRequest (req, res) {
 148   serve(req, res, finalhandler(req, res))
 149 })
 150
 151 // Listen
 152 server.listen(3000)
 153 ```
 154
 155 ### Serve all files as downloads
 156
 157 ```js
 158 var contentDisposition = require('content-disposition')
 159 var finalhandler = require('finalhandler')
 160 var http = require('http')
 161 var serveStatic = require('serve-static')
 162
 163 // Serve up public/ftp folder
 164 var serve = serveStatic('public/ftp', {
 165   'index': false,
 166   'setHeaders': setHeaders
 167 })
 168
 169 // Set header to force download
 170 function setHeaders (res, path) {
 171   res.setHeader('Content-Disposition', contentDisposition(path))
 172 }
 173
 174 // Create server
 175 var server = http.createServer(function onRequest (req, res) {
 176   serve(req, res, finalhandler(req, res))
 177 })
 178
 179 // Listen
 180 server.listen(3000)
 181 ```
 182
 183 ### Serving using express
 184
 185 #### Simple
 186
 187 This is a simple example of using Express.
 188
 189 ```js
 190 var express = require('express')
 191 var serveStatic = require('serve-static')
 192
 193 var app = express()
 194
 195 app.use(serveStatic('public/ftp', {'index': ['default.html', 'default.htm']}))
 196 app.listen(3000)
 197 ```
 198
 199 #### Multiple roots
 200
 201 This example shows a simple way to search through multiple directories.
 202 Files are look for in `public-optimized/` first, then `public/` second as
 203 a fallback.
 204
 205 ```js
 206 var express = require('express')
 207 var path = require('path')
 208 var serveStatic = require('serve-static')
 209
 210 var app = express()
 211
 212 app.use(serveStatic(path.join(__dirname, 'public-optimized')))
 213 app.use(serveStatic(path.join(__dirname, 'public')))
 214 app.listen(3000)
 215 ```
 216
 217 #### Different settings for paths
 218
 219 This example shows how to set a different max age depending on the served
 220 file type. In this example, HTML files are not cached, while everything else
 221 is for 1 day.
 222
 223 ```js
 224 var express = require('express')
 225 var path = require('path')
 226 var serveStatic = require('serve-static')
 227
 228 var app = express()
 229
 230 app.use(serveStatic(path.join(__dirname, 'public'), {
 231   maxAge: '1d',
 232   setHeaders: setCustomCacheControl
 233 }))
 234
 235 app.listen(3000)
 236
 237 function setCustomCacheControl (res, path) {
 238   if (serveStatic.mime.lookup(path) === 'text/html') {
 239     // Custom Cache-Control for HTML files
 240     res.setHeader('Cache-Control', 'public, max-age=0')
 241   }
 242 }
 243 ```
 244
 245 ## License
 246
 247 [MIT](LICENSE)
 248
 249 [npm-image]: https://img.shields.io/npm/v/serve-static.svg
 250 [npm-url]: https://npmjs.org/package/serve-static
 251 [travis-image]: https://img.shields.io/travis/expressjs/serve-static/master.svg?label=linux
 252 [travis-url]: https://travis-ci.org/expressjs/serve-static
 253 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-static/master.svg?label=windows
 254 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-static
 255 [coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-static/master.svg
 256 [coveralls-url]: https://coveralls.io/r/expressjs/serve-static
 257 [downloads-image]: https://img.shields.io/npm/dm/serve-static.svg
 258 [downloads-url]: https://npmjs.org/package/serve-static