1# Ecstatic [![build status](https://secure.travis-ci.org/jfhbrook/node-ecstatic.png)](http://travis-ci.org/jfhbrook/node-ecstatic)
  2
  3![](http://imgur.com/vhub5.png)
  4
  5A simple static file server middleware. Use it with a raw http server or
  6express/connect!
  7
  8# Examples:
  9
 10## express 3.0.x
 11
 12``` js
 13var http = require('http');
 14var express = require('express');
 15var ecstatic = require('ecstatic');
 16
 17var app = express();
 18app.use(ecstatic({ root: __dirname + '/public' }));
 19http.createServer(app).listen(8080);
 20
 21console.log('Listening on :8080');
 22```
 23
 24## stock http server
 25
 26``` js
 27var http = require('http');
 28var ecstatic = require('ecstatic');
 29
 30http.createServer(
 31  ecstatic({ root: __dirname + '/public' })
 32).listen(8080);
 33
 34console.log('Listening on :8080');
 35```
 36### fall through
 37To allow fall through to your custom routes:
 38
 39```js
 40ecstatic({ root: __dirname + '/public', handleError: false })
 41```
 42
 43# API:
 44
 45## ecstatic(opts);
 46
 47Pass ecstatic an options hash, and it will return your middleware!
 48
 49```js
 50var opts = {
 51             root               : __dirname + '/public',
 52             port               : 8000,
 53             baseDir            : '/',
 54             cache              : 3600,
 55             showDir            : true,
 56             showDotfiles       : true,
 57             autoIndex          : false,
 58             humanReadable      : true,
 59             headers            : {},
 60             si                 : false,
 61             defaultExt         : 'html',
 62             gzip               : false,
 63             serverHeader       : true,
 64             contentType        : 'application/octet-stream',
 65             mimeTypes          : undefined,
 66             handleOptionsMethod: false
 67           }
 68```
 69
 70If `opts` is a string, the string is assigned to the root folder and all other
 71options are set to their defaults.
 72
 73### `opts.root`
 74
 75`opts.root` is the directory you want to serve up.
 76
 77### `opts.port`
 78
 79`opts.port` is the port you want ecstatic to listen to. Defaults to 8000.
 80
 81### `opts.baseDir`
 82
 83`opts.baseDir` is `/` by default, but can be changed to allow your static files
 84to be served off a specific route. For example, if `opts.baseDir === "blog"`
 85and `opts.root = "./public"`, requests for `localhost:8080/blog/index.html` will
 86resolve to `./public/index.html`.
 87
 88### `opts.cache`
 89
 90Customize cache control with `opts.cache` , if it is a number then it will set max-age in seconds.
 91Other wise it will pass through directly to cache-control. Time defaults to 3600 s (ie, 1 hour).
 92
 93If it is a function, it will be executed on every request, and passed the pathname.  Whatever it returns, string or number, will be used as the cache control header like above.
 94
 95### `opts.showDir`
 96
 97Turn **off** directory listings with `opts.showDir === false`. Defaults to **true**.
 98
 99### `opts.showDotfiles`
100
101Exclude dotfiles from directory listings with `opts.showDotfiles === false`. Defaults to **true**.
102
103### `opts.humanReadable`
104
105If showDir is enabled, add human-readable file sizes. Defaults to **true**.
106Aliases are `humanreadable` and `human-readable`.
107
108### `opts.headers`
109
110Set headers on every response. `opts.headers` can be an object mapping string
111header names to string header values, a colon (:) separated string, or an array
112of colon separated strings.
113
114`opts.H` and `opts.header` are aliased to `opts.headers` so that you can use
115`-H` and `--header` options to set headers on the command-line like curl:
116
117``` sh
118$ ecstatic ./public -p 5000 -H 'Access-Control-Allow-Origin: *'
119```
120
121### `opts.si`
122
123If showDir and humanReadable are enabled, print file sizes with base 1000 instead
124of base 1024. Name is inferred from cli options for `ls`. Aliased to `index`, the
125equivalent option in Apache.
126
127### `opts.autoIndex`
128
129Serve `/path/index.html` when `/path/` is requested.
130Turn **off** autoIndexing with `opts.autoIndex === false`. Defaults to **true**.
131
132### `opts.defaultExt`
133
134Turn on default file extensions with `opts.defaultExt`. If `opts.defaultExt` is
135true, it will default to `html`. For example if you want a request to `/a-file`
136to resolve to `./public/a-file.html`, set this to `true`. If you want
137`/a-file` to resolve to `./public/a-file.json` instead, set `opts.defaultExt` to
138`json`.
139
140### `opts.gzip`
141
142Set `opts.gzip === true` in order to turn on "gzip mode," wherein ecstatic will
143serve `./public/some-file.js.gz` in place of `./public/some-file.js` when the
144gzipped version exists and ecstatic determines that the behavior is appropriate.
145
146### `opts.serverHeader`
147
148Set `opts.serverHeader` to false in order to turn off setting the `Server` header
149on all responses served by ecstatic.
150
151### `opts.contentType`
152
153Set `opts.contentType` in order to change default Content-Type header value.
154Defaults to **application/octet-stream**.
155
156### `opts.mimeTypes`
157
158Add new or override one or more mime-types. This affects the HTTP Content-Type header.
159Can either be a path to a [`.types`](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types) file or an object hash of type(s).
160
161    ecstatic({ mimeType: { 'mime-type': ['file_extension', 'file_extension'] } })
162
163### `opts.handleError`
164
165Turn **off** handleErrors to allow fall-through with `opts.handleError === false`, Defaults to **true**.
166
167### `opts.weakEtags`
168
169Set `opts.weakEtags` to true in order to generate weak etags instead of strong etags. Defaults to **false**. See `opts.weakCompare` as well.
170
171### `opts.weakCompare`
172
173Turn **on** weakCompare to allow the weak comparison function for etag validation. Defaults to **false**.
174See https://www.ietf.org/rfc/rfc2616.txt Section 13.3.3 for more details.
175
176### `opts.handleOptionsMethod`
177
178Set handleOptionsMethod to true in order to respond to 'OPTIONS' calls with any standard/set headers. Defaults to **false**. Useful for hacking up CORS support.
179
180### `opts.cors`
181
182This is a **convenience** setting which turns on `handleOptionsMethod` and sets the headers **Access-Control-Allow-Origin: \*** and **Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since**. This *should* be enough to quickly make cross-origin resource sharing work between development APIs. More advanced usage can come either from overriding these headers with the headers argument, or by using the `handleOptionsMethod` flag and then setting headers "manually." Alternately, just do it in your app using separate middlewares/abstractions.
183
184Defaults to **false**.
185
186## middleware(req, res, next);
187
188This works more or less as you'd expect.
189
190### ecstatic.showDir(folder);
191
192This returns another middleware which will attempt to show a directory view. Turning on auto-indexing is roughly equivalent to adding this middleware after an ecstatic middleware with autoindexing disabled.
193
194### `ecstatic` command
195
196to start a standalone static http server,
197run `npm install -g ecstatic` and then run `ecstatic [dir?] [options] --port PORT`
198all options work as above, passed in [optimist](https://github.com/substack/node-optimist) style.
199`port` defaults to `8000`. If a `dir` or `--root dir` argument is not passed, ecsatic will
200serve the current dir. Ecstatic also respects the PORT environment variable.
201
202# Tests:
203
204Ecstatic has a fairly extensive test suite. You can run it with:
205
206```sh
207$ npm test
208```
209
210# Contribute:
211
212Without outside contributions, ecstatic would wither and die! Before
213contributing, take a quick look at the contributing guidelines in
214[./CONTRIBUTING.md](./CONTRIBUTING.md) . They're relatively painless, I promise.
215For Windows users, it is especially important to read the [./CONTRIBUTING.md](./CONTRIBUTING.md)
216section as you can **not** clone ecstatic without changing some settings in git.
217
218# License:
219
220MIT. See LICENSE.txt. For contributors, see CONTRIBUTORS.md