You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

258 lines
7.6 KiB

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