source: trip-planner-front/node_modules/serve-static/README.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 7.6 KB
Line 
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
11This 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
24var serveStatic = require('serve-static')
25```
26
27### serveStatic(root, options)
28
29Create a new middleware function to serve files from within a given root
30directory. The file to serve will be determined by combining `req.url`
31with the provided root directory. When a file is not found, instead of
32sending a 404 response, this module will instead call `next()` to move on
33to the next middleware, allowing for stacking and fall-backs.
34
35#### Options
36
37##### acceptRanges
38
39Enable or disable accepting ranged requests, defaults to true.
40Disabling this will not send `Accept-Ranges` and ignore the contents
41of the `Range` request header.
42
43##### cacheControl
44
45Enable or disable setting `Cache-Control` response header, defaults to
46true. 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
51or directory that begins with a dot ("."). Note this check is done on
52the path itself without checking if the path actually exists on the
53disk. If `root` is specified, only the dotfiles above the root are
54checked (i.e. the root itself can be within a dotfile when set
55to "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
61The default value is similar to `'ignore'`, with the exception that this
62default will not ignore the files within a directory that begins with a dot.
63
64##### etag
65
66Enable or disable etag generation, defaults to true.
67
68##### extensions
69
70Set file extension fallbacks. When set, if a file is not found, the given
71extensions will be added to the file name and search for. The first that
72exists will be served. Example: `['html', 'htm']`.
73
74The default value is `false`.
75
76##### fallthrough
77
78Set the middleware to have client errors fall-through as just unhandled
79requests, otherwise forward a client error. The difference is that client
80errors like a bad request or a request to a non-existent file will cause
81this middleware to simply `next()` to your next middleware when this value
82is `true`. When this value is `false`, these errors (even 404s), will invoke
83`next(err)`.
84
85Typically `true` is desired such that multiple physical directories can be
86mapped to the same web address or for routes to fill in non-existent files.
87
88The value `false` can be used if this middleware is mounted at a path that
89is designed to be strictly a single file system directory, which allows for
90short-circuiting 404s for less overhead. This middleware will also reply to
91all methods.
92
93The default value is `true`.
94
95##### immutable
96
97Enable or disable the `immutable` directive in the `Cache-Control` response
98header, defaults to `false`. If set to `true`, the `maxAge` option should
99also be specified to enable caching. The `immutable` directive will prevent
100supported clients from making conditional requests during the life of the
101`maxAge` option to check if the file has changed.
102
103##### index
104
105By default this module will send "index.html" files in response to a request
106on a directory. To disable this set `false` or to supply a new index pass a
107string or an array in preferred order.
108
109##### lastModified
110
111Enable or disable `Last-Modified` header, defaults to true. Uses the file
112system's last modified value.
113
114##### maxAge
115
116Provide a max-age in milliseconds for http caching, defaults to 0. This
117can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
118module.
119
120##### redirect
121
122Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.
123
124##### setHeaders
125
126Function to set custom headers on response. Alterations to the headers need to
127occur synchronously. The function is called as `fn(res, path, stat)`, where
128the 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
139var finalhandler = require('finalhandler')
140var http = require('http')
141var serveStatic = require('serve-static')
142
143// Serve up public/ftp folder
144var serve = serveStatic('public/ftp', { 'index': ['index.html', 'index.htm'] })
145
146// Create server
147var server = http.createServer(function onRequest (req, res) {
148 serve(req, res, finalhandler(req, res))
149})
150
151// Listen
152server.listen(3000)
153```
154
155### Serve all files as downloads
156
157```js
158var contentDisposition = require('content-disposition')
159var finalhandler = require('finalhandler')
160var http = require('http')
161var serveStatic = require('serve-static')
162
163// Serve up public/ftp folder
164var serve = serveStatic('public/ftp', {
165 'index': false,
166 'setHeaders': setHeaders
167})
168
169// Set header to force download
170function setHeaders (res, path) {
171 res.setHeader('Content-Disposition', contentDisposition(path))
172}
173
174// Create server
175var server = http.createServer(function onRequest (req, res) {
176 serve(req, res, finalhandler(req, res))
177})
178
179// Listen
180server.listen(3000)
181```
182
183### Serving using express
184
185#### Simple
186
187This is a simple example of using Express.
188
189```js
190var express = require('express')
191var serveStatic = require('serve-static')
192
193var app = express()
194
195app.use(serveStatic('public/ftp', { 'index': ['default.html', 'default.htm'] }))
196app.listen(3000)
197```
198
199#### Multiple roots
200
201This example shows a simple way to search through multiple directories.
202Files are look for in `public-optimized/` first, then `public/` second as
203a fallback.
204
205```js
206var express = require('express')
207var path = require('path')
208var serveStatic = require('serve-static')
209
210var app = express()
211
212app.use(serveStatic(path.join(__dirname, 'public-optimized')))
213app.use(serveStatic(path.join(__dirname, 'public')))
214app.listen(3000)
215```
216
217#### Different settings for paths
218
219This example shows how to set a different max age depending on the served
220file type. In this example, HTML files are not cached, while everything else
221is for 1 day.
222
223```js
224var express = require('express')
225var path = require('path')
226var serveStatic = require('serve-static')
227
228var app = express()
229
230app.use(serveStatic(path.join(__dirname, 'public'), {
231 maxAge: '1d',
232 setHeaders: setCustomCacheControl
233}))
234
235app.listen(3000)
236
237function 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
Note: See TracBrowser for help on using the repository browser.