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]
9 Send is a library for streaming files from the file system as a http response
10 supporting partial responses (Ranges), conditional-GET negotiation (If-Match,
11 If-Unmodified-Since, If-None-Match, If-Modified-Since), high test coverage,
12 and granular events which may be leveraged to take appropriate actions in your
13 application or framework.
15 Looking to serve up entire folders mapped to URLs? Try [serve-static](https://www.npmjs.org/package/serve-static).
19 This is a [Node.js](https://nodejs.org/en/) module available through the
20 [npm registry](https://www.npmjs.com/). Installation is done using the
21 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
29 <!-- eslint-disable no-unused-vars -->
32 var send = require('send')
35 ### send(req, path, [options])
37 Create a new `SendStream` for the given path to send to a `res`. The `req` is
38 the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
39 not the actual file-system path).
45 Enable or disable accepting ranged requests, defaults to true.
46 Disabling this will not send `Accept-Ranges` and ignore the contents
47 of the `Range` request header.
51 Enable or disable setting `Cache-Control` response header, defaults to
52 true. Disabling this will ignore the `immutable` and `maxAge` options.
56 Set how "dotfiles" are treated when encountered. A dotfile is a file
57 or directory that begins with a dot ("."). Note this check is done on
58 the path itself without checking if the path actually exists on the
59 disk. If `root` is specified, only the dotfiles above the root are
60 checked (i.e. the root itself can be within a dotfile when when set
63 - `'allow'` No special treatment for dotfiles.
64 - `'deny'` Send a 403 for any request for a dotfile.
65 - `'ignore'` Pretend like the dotfile does not exist and 404.
67 The default value is _similar_ to `'ignore'`, with the exception that
68 this default will not ignore the files within a directory that begins
69 with a dot, for backward-compatibility.
73 Byte offset at which the stream ends, defaults to the length of the file
74 minus 1. The end is inclusive in the stream, meaning `end: 3` will include
75 the 4th byte in the stream.
79 Enable or disable etag generation, defaults to true.
83 If a given file doesn't exist, try appending one of the given extensions,
84 in the given order. By default, this is disabled (set to `false`). An
85 example value that will serve extension-less HTML files: `['html', 'htm']`.
86 This is skipped if the requested file already has an extension.
90 Enable or diable the `immutable` directive in the `Cache-Control` response
91 header, defaults to `false`. If set to `true`, the `maxAge` option should
92 also be specified to enable caching. The `immutable` directive will prevent
93 supported clients from making conditional requests during the life of the
94 `maxAge` option to check if the file has changed.
98 By default send supports "index.html" files, to disable this
99 set `false` or to supply a new index pass a string or an array
104 Enable or disable `Last-Modified` header, defaults to true. Uses the file
105 system's last modified value.
109 Provide a max-age in milliseconds for http caching, defaults to 0.
110 This can also be a string accepted by the
111 [ms](https://www.npmjs.org/package/ms#readme) module.
115 Serve files relative to `path`.
119 Byte offset at which the stream starts, defaults to 0. The start is inclusive,
120 meaning `start: 2` will include the 3rd byte in the stream.
124 The `SendStream` is an event emitter and will emit the following events:
126 - `error` an error occurred `(err)`
127 - `directory` a directory was requested `(res, path)`
128 - `file` a file was requested `(path, stat)`
129 - `headers` the headers are about to be set on a file `(res, path, stat)`
130 - `stream` file streaming has started `(stream)`
131 - `end` streaming has completed
135 The `pipe` method is used to pipe the response into the Node.js HTTP response
136 object, typically `send(req, path, options).pipe(res)`.
140 The `mime` export is the global instance of of the
141 [`mime` npm module](https://www.npmjs.com/package/mime).
143 This is used to configure the MIME types that are associated with file extensions
144 as well as other options for how to resolve the MIME type of a file (like the
145 default type to use for an unknown file extension).
149 By default when no `error` listeners are present an automatic response will be
150 made, otherwise you have full control over the response, aka you may show a 5xx
155 It does _not_ perform internal caching, you should use a reverse proxy cache
156 such as Varnish for this, or those fancy things called CDNs. If your
157 application is small enough that it would benefit from single-node memory
158 caching, it's small enough that it does not need caching at all ;).
162 To enable `debug()` instrumentation output export __DEBUG__:
165 $ DEBUG=send node app
180 var http = require('http')
181 var parseUrl = require('parseurl')
182 var send = require('send')
184 var server = http.createServer(function onRequest (req, res) {
185 send(req, parseUrl(req).pathname).pipe(res)
191 ### Custom file types
194 var http = require('http')
195 var parseUrl = require('parseurl')
196 var send = require('send')
198 // Default unknown types to text/plain
199 send.mime.default_type = 'text/plain'
203 'application/x-my-type': ['x-mt', 'x-mtt']
206 var server = http.createServer(function onRequest (req, res) {
207 send(req, parseUrl(req).pathname).pipe(res)
213 ### Custom directory index view
215 This is a example of serving up a structure of directories with a
216 custom function to render a listing of a directory.
219 var http = require('http')
220 var fs = require('fs')
221 var parseUrl = require('parseurl')
222 var send = require('send')
224 // Transfer arbitrary files from within /www/example.com/public/*
225 // with a custom handler for directory listing
226 var server = http.createServer(function onRequest (req, res) {
227 send(req, parseUrl(req).pathname, {index: false, root: '/www/example.com/public'})
228 .once('directory', directory)
234 // Custom directory handler
235 function directory (res, path) {
238 // redirect to trailing slash for consistent url
239 if (!stream.hasTrailingSlash()) {
240 return stream.redirect(path)
243 // get directory list
244 fs.readdir(path, function onReaddir (err, list) {
245 if (err) return stream.error(err)
247 // render an index for the directory
248 res.setHeader('Content-Type', 'text/plain; charset=UTF-8')
249 res.end(list.join('\n') + '\n')
254 ### Serving from a root directory with custom error-handling
257 var http = require('http')
258 var parseUrl = require('parseurl')
259 var send = require('send')
261 var server = http.createServer(function onRequest (req, res) {
262 // your custom error-handling logic:
263 function error (err) {
264 res.statusCode = err.status || 500
268 // your custom headers
269 function headers (res, path, stat) {
270 // serve all files for download
271 res.setHeader('Content-Disposition', 'attachment')
274 // your custom directory handling logic:
275 function redirect () {
277 res.setHeader('Location', req.url + '/')
278 res.end('Redirecting to ' + req.url + '/')
281 // transfer arbitrary files from within
282 // /www/example.com/public/*
283 send(req, parseUrl(req).pathname, {root: '/www/example.com/public'})
285 .on('directory', redirect)
286 .on('headers', headers)
297 [npm-image]: https://img.shields.io/npm/v/send.svg
298 [npm-url]: https://npmjs.org/package/send
299 [travis-image]: https://img.shields.io/travis/pillarjs/send/master.svg?label=linux
300 [travis-url]: https://travis-ci.org/pillarjs/send
301 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/send/master.svg?label=windows
302 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
303 [coveralls-image]: https://img.shields.io/coveralls/pillarjs/send/master.svg
304 [coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
305 [downloads-image]: https://img.shields.io/npm/dm/send.svg
306 [downloads-url]: https://npmjs.org/package/send