AK-21/Graphite-Industrial-Intelligence

1# serve-static2 3[![NPM Version][npm-version-image]][npm-url]4[![NPM Downloads][npm-downloads-image]][npm-url]5[![CI][github-actions-ci-image]][github-actions-ci-url]6[![Test Coverage][coveralls-image]][coveralls-url]7 8## Install9 10This is a [Node.js](https://nodejs.org/en/) module available through the11[npm registry](https://www.npmjs.com/). Installation is done using the12[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):13 14```sh15$ npm install serve-static16```17 18## API19 20```js21const serveStatic = require('serve-static')22```23 24### serveStatic(root, options)25 26Create a new middleware function to serve files from within a given root27directory. The file to serve will be determined by combining `req.url`28with the provided root directory. When a file is not found, instead of29sending a 404 response, this module will instead call `next()` to move on30to the next middleware, allowing for stacking and fall-backs.31 32#### Options33 34##### acceptRanges35 36Enable or disable accepting ranged requests, defaults to true.37Disabling this will not send `Accept-Ranges` and ignore the contents38of the `Range` request header.39 40##### cacheControl41 42Enable or disable setting `Cache-Control` response header, defaults to43true. Disabling this will ignore the `immutable` and `maxAge` options.44 45##### dotfiles46 47Set how "dotfiles" are treated when encountered. A dotfile is a file48or directory that begins with a dot ("."). Note this check is done on49the path itself without checking if the path actually exists on the50disk. If `root` is specified, only the dotfiles above the root are51checked (i.e. the root itself can be within a dotfile when set52to "deny").53 54  - `'allow'` No special treatment for dotfiles.55  - `'deny'` Deny a request for a dotfile and 403/`next()`.56  - `'ignore'` Pretend like the dotfile does not exist and 404/`next()`.57 58The default value is `'ignore'`.59 60##### etag61 62Enable or disable etag generation, defaults to true.63 64##### extensions65 66Set file extension fallbacks. When set, if a file is not found, the given67extensions will be added to the file name and search for. The first that68exists will be served. Example: `['html', 'htm']`.69 70The default value is `false`.71 72##### fallthrough73 74Set the middleware to have client errors fall-through as just unhandled75requests, otherwise forward a client error. The difference is that client76errors like a bad request or a request to a non-existent file will cause77this middleware to simply `next()` to your next middleware when this value78is `true`. When this value is `false`, these errors (even 404s), will invoke79`next(err)`.80 81Typically `true` is desired such that multiple physical directories can be82mapped to the same web address or for routes to fill in non-existent files.83 84The value `false` can be used if this middleware is mounted at a path that85is designed to be strictly a single file system directory, which allows for86short-circuiting 404s for less overhead. This middleware will also reply to87all methods.88 89The default value is `true`.90 91##### immutable92 93Enable or disable the `immutable` directive in the `Cache-Control` response94header, defaults to `false`. If set to `true`, the `maxAge` option should95also be specified to enable caching. The `immutable` directive will prevent96supported clients from making conditional requests during the life of the97`maxAge` option to check if the file has changed.98 99##### index100 101By default this module will send "index.html" files in response to a request102on a directory. To disable this set `false` or to supply a new index pass a103string or an array in preferred order.104 105##### lastModified106 107Enable or disable `Last-Modified` header, defaults to true. Uses the file108system's last modified value.109 110##### maxAge111 112Provide a max-age in milliseconds for http caching, defaults to 0. This113can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)114module.115 116##### redirect117 118Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.119 120##### setHeaders121 122Function to set custom headers on response. Alterations to the headers need to123occur synchronously. The function is called as `fn(res, path, stat)`, where124the arguments are:125 126  - `res` the response object127  - `path` the file path that is being sent128  - `stat` the stat object of the file that is being sent129 130## Examples131 132### Serve files with vanilla node.js http server133 134```js135const finalhandler = require('finalhandler')136const http = require('http')137const serveStatic = require('serve-static')138 139// Serve up public/ftp folder140const serve = serveStatic('public/ftp', { index: ['index.html', 'index.htm'] })141 142// Create server143const server = http.createServer((req, res) => {144  serve(req, res, finalhandler(req, res))145})146 147// Listen148server.listen(3000)149```150 151### Serve all files as downloads152 153```js154const contentDisposition = require('content-disposition')155const finalhandler = require('finalhandler')156const http = require('http')157const serveStatic = require('serve-static')158 159// Serve up public/ftp folder160const serve = serveStatic('public/ftp', {161  index: false,162  setHeaders: setHeaders163})164 165// Set header to force download166function setHeaders (res, path) {167  res.setHeader('Content-Disposition', contentDisposition(path))168}169 170// Create server171const server = http.createServer((req, res) => {172  serve(req, res, finalhandler(req, res))173})174 175// Listen176server.listen(3000)177```178 179### Serving using express180 181#### Simple182 183This is a simple example of using Express.184 185```js186const express = require('express')187const serveStatic = require('serve-static')188 189const app = express()190 191app.use(serveStatic('public/ftp', { index: ['default.html', 'default.htm'] }))192app.listen(3000)193```194 195#### Multiple roots196 197This example shows a simple way to search through multiple directories.198Files are searched for in `public-optimized/` first, then `public/` second199as a fallback.200 201```js202const express = require('express')203const path = require('path')204const serveStatic = require('serve-static')205 206const app = express()207 208app.use(serveStatic(path.join(__dirname, 'public-optimized')))209app.use(serveStatic(path.join(__dirname, 'public')))210app.listen(3000)211```212 213#### Different settings for paths214 215This example shows how to set a different max age depending on the served216file. In this example, HTML files are not cached, while everything else217is for 1 day.218 219```js220const express = require('express')221const path = require('path')222const serveStatic = require('serve-static')223 224const app = express()225 226app.use(serveStatic(path.join(__dirname, 'public'), {227  maxAge: '1d',228  setHeaders: setCustomCacheControl229}))230 231app.listen(3000)232 233function setCustomCacheControl (res, file) {234  if (path.extname(file) === '.html') {235    // Custom Cache-Control for HTML files236    res.setHeader('Cache-Control', 'public, max-age=0')237  }238}239```240 241## License242 243[MIT](LICENSE)244 245[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/serve-static/master246[coveralls-url]: https://coveralls.io/r/expressjs/serve-static?branch=master247[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/serve-static/master?label=linux248[github-actions-ci-url]: https://github.com/expressjs/serve-static/actions/workflows/ci.yml249[node-image]: https://badgen.net/npm/node/serve-static250[node-url]: https://nodejs.org/en/download/251[npm-downloads-image]: https://badgen.net/npm/dm/serve-static252[npm-url]: https://npmjs.org/package/serve-static253[npm-version-image]: https://badgen.net/npm/v/serve-static254