3 [![NPM Version][npm-image]][npm-url]
4 [![NPM Downloads][downloads-image]][downloads-url]
5 [![Build Status][travis-image]][travis-url]
6 [![Test Coverage][coveralls-image]][coveralls-url]
7 [![Gittip][gittip-image]][gittip-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, high test
11 coverage, and granular events which may be leveraged to take appropriate actions
12 in your application or framework.
14 Looking to serve up entire folders mapped to URLs? Try [serve-static](https://www.npmjs.org/package/serve-static).
25 var send = require('send')
28 ### send(req, path, [options])
30 Create a new `SendStream` for the given path to send to a `res`. The `req` is
31 the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
32 not the actual file-system path).
38 Set how "dotfiles" are treated when encountered. A dotfile is a file
39 or directory that begins with a dot ("."). Note this check is done on
40 the path itself without checking if the path actually exists on the
41 disk. If `root` is specified, only the dotfiles above the root are
42 checked (i.e. the root itself can be within a dotfile when when set
45 - `'allow'` No special treatment for dotfiles.
46 - `'deny'` Send a 403 for any request for a dotfile.
47 - `'ignore'` Pretend like the dotfile does not exist and 404.
49 The default value is _similar_ to `'ignore'`, with the exception that
50 this default will not ignore the files within a directory that begins
51 with a dot, for backward-compatibility.
55 Enable or disable etag generation, defaults to true.
59 If a given file doesn't exist, try appending one of the given extensions,
60 in the given order. By default, this is disabled (set to `false`). An
61 example value that will serve extension-less HTML files: `['html', 'htm']`.
62 This is skipped if the requested file already has an extension.
66 By default send supports "index.html" files, to disable this
67 set `false` or to supply a new index pass a string or an array
72 Enable or disable `Last-Modified` header, defaults to true. Uses the file
73 system's last modified value.
77 Provide a max-age in milliseconds for http caching, defaults to 0.
78 This can also be a string accepted by the
79 [ms](https://www.npmjs.org/package/ms#readme) module.
83 Serve files relative to `path`.
87 The `SendStream` is an event emitter and will emit the following events:
89 - `error` an error occurred `(err)`
90 - `directory` a directory was requested
91 - `file` a file was requested `(path, stat)`
92 - `headers` the headers are about to be set on a file `(res, path, stat)`
93 - `stream` file streaming has started `(stream)`
94 - `end` streaming has completed
98 The `pipe` method is used to pipe the response into the Node.js HTTP response
99 object, typically `send(req, path, options).pipe(res)`.
103 By default when no `error` listeners are present an automatic response will be
104 made, otherwise you have full control over the response, aka you may show a 5xx
109 It does _not_ perform internal caching, you should use a reverse proxy cache
110 such as Varnish for this, or those fancy things called CDNs. If your
111 application is small enough that it would benefit from single-node memory
112 caching, it's small enough that it does not need caching at all ;).
116 To enable `debug()` instrumentation output export __DEBUG__:
119 $ DEBUG=send node app
134 var http = require('http');
135 var send = require('send');
137 var app = http.createServer(function(req, res){
138 send(req, req.url).pipe(res);
142 Serving from a root directory with custom error-handling:
145 var http = require('http');
146 var send = require('send');
147 var url = require('url');
149 var app = http.createServer(function(req, res){
150 // your custom error-handling logic:
151 function error(err) {
152 res.statusCode = err.status || 500;
153 res.end(err.message);
156 // your custom headers
157 function headers(res, path, stat) {
158 // serve all files for download
159 res.setHeader('Content-Disposition', 'attachment');
162 // your custom directory handling logic:
163 function redirect() {
164 res.statusCode = 301;
165 res.setHeader('Location', req.url + '/');
166 res.end('Redirecting to ' + req.url + '/');
169 // transfer arbitrary files from within
170 // /www/example.com/public/*
171 send(req, url.parse(req.url).pathname, {root: '/www/example.com/public'})
173 .on('directory', redirect)
174 .on('headers', headers)
183 [npm-image]: https://img.shields.io/npm/v/send.svg?style=flat
184 [npm-url]: https://npmjs.org/package/send
185 [travis-image]: https://img.shields.io/travis/tj/send.svg?style=flat
186 [travis-url]: https://travis-ci.org/tj/send
187 [coveralls-image]: https://img.shields.io/coveralls/tj/send.svg?style=flat
188 [coveralls-url]: https://coveralls.io/r/tj/send?branch=master
189 [downloads-image]: https://img.shields.io/npm/dm/send.svg?style=flat
190 [downloads-url]: https://npmjs.org/package/send
191 [gittip-image]: https://img.shields.io/gittip/dougwilson.svg?style=flat
192 [gittip-url]: https://www.gittip.com/dougwilson/