README.md (7783B)
1 # serve-static 2 3 [![NPM Version][npm-version-image]][npm-url] 4 [![NPM Downloads][npm-downloads-image]][npm-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 [appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/serve-static/master?label=windows 250 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-static 251 [coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/serve-static/master 252 [coveralls-url]: https://coveralls.io/r/expressjs/serve-static?branch=master 253 [node-image]: https://badgen.net/npm/node/serve-static 254 [node-url]: https://nodejs.org/en/download/ 255 [npm-downloads-image]: https://badgen.net/npm/dm/serve-static 256 [npm-url]: https://npmjs.org/package/serve-static 257 [npm-version-image]: https://badgen.net/npm/v/serve-static 258 [travis-image]: https://badgen.net/travis/expressjs/serve-static/master?label=linux 259 [travis-url]: https://travis-ci.org/expressjs/serve-static