300 lines
9.0 KiB
Markdown
300 lines
9.0 KiB
Markdown
# Ecstatic [](http://travis-ci.org/jfhbrook/node-ecstatic) [](https://codecov.io/github/jfhbrook/node-ecstatic?branch=master)
|
|
|
|
|
|
|
|
A simple static file server middleware. Use it with a raw http server,
|
|
express/connect or on the CLI!
|
|
|
|
# Examples:
|
|
|
|
## express 4.x
|
|
|
|
``` js
|
|
'use strict';
|
|
|
|
const express = require('express');
|
|
const ecstatic = require('../lib/ecstatic');
|
|
const http = require('http');
|
|
|
|
const app = express();
|
|
|
|
app.use(ecstatic({
|
|
root: `${__dirname}/public`,
|
|
showdir: true,
|
|
}));
|
|
|
|
http.createServer(app).listen(8080);
|
|
|
|
console.log('Listening on :8080');
|
|
```
|
|
|
|
## stock http server
|
|
|
|
``` js
|
|
'use strict';
|
|
|
|
const http = require('http');
|
|
|
|
const ecstatic = require('../lib/ecstatic')({
|
|
root: `${__dirname}/public`,
|
|
showDir: true,
|
|
autoIndex: true,
|
|
});
|
|
|
|
http.createServer(ecstatic).listen(8080);
|
|
|
|
console.log('Listening on :8080');
|
|
```
|
|
|
|
### fall through
|
|
To allow fall through to your custom routes:
|
|
|
|
```js
|
|
ecstatic({ root: __dirname + '/public', handleError: false })
|
|
```
|
|
|
|
## CLI
|
|
|
|
```sh
|
|
ecstatic ./public --port 8080
|
|
```
|
|
|
|
# Install:
|
|
|
|
For using ecstatic as a library, just npm install it into your project:
|
|
|
|
```sh
|
|
npm install --save ecstatic
|
|
```
|
|
|
|
For using ecstatic as a cli tool, either npm install it globally:
|
|
|
|
```sh
|
|
npm install ecstatic -g
|
|
```
|
|
|
|
or install it locally and use npm runscripts to add it to your $PATH, or
|
|
reference it directly with `./node_modules/.bin/ecstatic`.
|
|
|
|
|
|
# API:
|
|
|
|
## ecstatic(opts);
|
|
## $ ecstatic [dir?] {options} --port PORT
|
|
|
|
In node, pass ecstatic an options hash, and it will return your middleware!
|
|
|
|
```js
|
|
const opts = {
|
|
root: path.join(__dirname, 'public'),
|
|
baseDir: '/',
|
|
autoIndex: true,
|
|
showDir: true,
|
|
showDotfiles: true,
|
|
humanReadable: true,
|
|
hidePermissions: false,
|
|
si: false,
|
|
cache: 'max-age=3600',
|
|
cors: false,
|
|
gzip: true,
|
|
brotli: false,
|
|
defaultExt: 'html',
|
|
handleError: true,
|
|
serverHeader: true,
|
|
contentType: 'application/octet-stream',
|
|
weakEtags: true,
|
|
weakCompare: true,
|
|
handleOptionsMethod: false,
|
|
}
|
|
```
|
|
|
|
If `opts` is a string, the string is assigned to the root folder and all other
|
|
options are set to their defaults.
|
|
|
|
When running in CLI mode, all options work as above, passed in
|
|
[optimist](https://github.com/substack/node-optimist) style. `port` defaults to
|
|
`8000`. If a `dir` or `--root dir` argument is not passed, ecsatic will
|
|
serve the current dir. Ecstatic also respects the PORT environment variable.
|
|
|
|
### `opts.root`
|
|
### `--root {root}`
|
|
|
|
`opts.root` is the directory you want to serve up.
|
|
|
|
### `opts.port`
|
|
### `--port {port}`
|
|
|
|
In CLI mode, `opts.port` is the port you want ecstatic to listen to. Defaults
|
|
to 8000. This can be overridden with the `--port` flag or with the PORT
|
|
environment variable.
|
|
|
|
### `opts.baseDir`
|
|
### `--baseDir {dir}`
|
|
|
|
`opts.baseDir` is `/` by default, but can be changed to allow your static files
|
|
to be served off a specific route. For example, if `opts.baseDir === "blog"`
|
|
and `opts.root = "./public"`, requests for `localhost:8080/blog/index.html` will
|
|
resolve to `./public/index.html`.
|
|
|
|
### `opts.cache`
|
|
### `--cache {value}`
|
|
|
|
Customize cache control with `opts.cache` , if it is a number then it will set max-age in seconds.
|
|
Other wise it will pass through directly to cache-control. Time defaults to 3600 s (ie, 1 hour).
|
|
|
|
If 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.
|
|
|
|
### `opts.showDir`
|
|
### `--no-showDir`
|
|
|
|
Turn **off** directory listings with `opts.showDir === false`. Defaults to **true**.
|
|
|
|
### `opts.showDotfiles`
|
|
### `--no-showDotfiles`
|
|
|
|
Exclude dotfiles from directory listings with `opts.showDotfiles === false`. Defaults to **true**.
|
|
|
|
### `opts.humanReadable`
|
|
### `--no-human-readable`
|
|
|
|
If showDir is enabled, add human-readable file sizes. Defaults to **true**.
|
|
Aliases are `humanreadable` and `human-readable`.
|
|
|
|
### `opts.hidePermissions`
|
|
### `--hide-permissions`
|
|
If hidePermissions is enabled, file permissions will not be displayed. Defaults to **false**.
|
|
Aliases are `hidepermissions` and `hide-permissions`.
|
|
|
|
### `opts.headers`
|
|
### `--H {HeaderA: valA} [--H {HeaderB: valB}]`
|
|
|
|
Set headers on every response. `opts.headers` can be an object mapping string
|
|
header names to string header values, a colon (:) separated string, or an array
|
|
of colon separated strings.
|
|
|
|
`opts.H` and `opts.header` are aliased to `opts.headers` so that you can use
|
|
`-H` and `--header` options to set headers on the command-line like curl:
|
|
|
|
``` sh
|
|
$ ecstatic ./public -p 5000 -H 'Access-Control-Allow-Origin: *'
|
|
```
|
|
|
|
### `opts.si`
|
|
### `--si`
|
|
|
|
If showDir and humanReadable are enabled, print file sizes with base 1000 instead
|
|
of base 1024. Name is inferred from cli options for `ls`. Aliased to `index`, the
|
|
equivalent option in Apache.
|
|
|
|
### `opts.autoIndex`
|
|
### `--no-autoindex`
|
|
|
|
Serve `/path/index.html` when `/path/` is requested.
|
|
Turn **off** autoIndexing with `opts.autoIndex === false`. Defaults to **true**.
|
|
|
|
### `opts.defaultExt`
|
|
### `--defaultExt {ext}`
|
|
|
|
Turn on default file extensions with `opts.defaultExt`. If `opts.defaultExt` is
|
|
true, it will default to `html`. For example if you want a request to `/a-file`
|
|
to resolve to `./public/a-file.html`, set this to `true`. If you want
|
|
`/a-file` to resolve to `./public/a-file.json` instead, set `opts.defaultExt` to
|
|
`json`.
|
|
|
|
### `opts.gzip`
|
|
### `--no-gzip`
|
|
|
|
By default, ecstatic will serve `./public/some-file.js.gz` in place of
|
|
`./public/some-file.js` when the gzipped version exists and ecstatic determines
|
|
that the behavior is appropriate. If `./public/some-file.js.gz` is not valid
|
|
gzip, this will fall back to `./public/some-file.js`. You can turn this off
|
|
with `opts.gzip === false`.
|
|
|
|
### `opts.brotli`
|
|
### `--brotli`
|
|
|
|
Serve `./public/some-file.js.br` in place of `./public/some-file.js` when the
|
|
[brotli encoded](https://github.com/google/brotli) version exists and ecstatic
|
|
determines that the behavior is appropriate. If the request does not contain
|
|
`br` in the HTTP `accept-encoding` header, ecstatic will instead attempt to
|
|
serve a gzipped version (if `opts.gzip` is `true`), or fall back to
|
|
`./public.some-file.js`. Defaults to **false**.
|
|
|
|
### `opts.serverHeader`
|
|
### `--no-server-header`
|
|
|
|
Set `opts.serverHeader` to false in order to turn off setting the `Server`
|
|
header on all responses served by ecstatic.
|
|
|
|
### `opts.contentType`
|
|
### `--content-type {type}`
|
|
|
|
Set `opts.contentType` in order to change default Content-Type header value.
|
|
Defaults to **application/octet-stream**.
|
|
|
|
### `opts.mimeTypes`
|
|
### `--mime-types {filename}`
|
|
|
|
Add new or override one or more mime-types. This affects the HTTP Content-Type
|
|
header. Can 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).
|
|
|
|
ecstatic({ mimeTypes: { 'mime-type': ['file_extension', 'file_extension'] } })
|
|
|
|
### `opts.handleError`
|
|
|
|
Turn **off** handleErrors to allow fall-through with
|
|
`opts.handleError === false`, Defaults to **true**.
|
|
|
|
### `opts.weakEtags`
|
|
### `--no-weak-etags`
|
|
|
|
Set `opts.weakEtags` to false in order to generate strong etags instead of
|
|
weak etags. Defaults to **true**. See `opts.weakCompare` as well.
|
|
|
|
### `opts.weakCompare`
|
|
### `--no-weak-compare`
|
|
|
|
Turn off weakCompare to disable the weak comparison function for etag
|
|
validation. Defaults to **true**. See
|
|
https://www.ietf.org/rfc/rfc2616.txt Section 13.3.3 for more details.
|
|
|
|
### `opts.handleOptionsMethod`
|
|
### `--handle-options-method`
|
|
|
|
Set handleOptionsMethod to true in order to respond to 'OPTIONS' calls with any standard/set headers. Defaults to **false**. Useful for hacking up CORS support.
|
|
|
|
### `opts.cors`
|
|
### `--cors`
|
|
|
|
This 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.
|
|
|
|
Defaults to **false**.
|
|
|
|
## middleware(req, res, next);
|
|
|
|
This works more or less as you'd expect.
|
|
|
|
### ecstatic.showDir(folder);
|
|
|
|
This 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.
|
|
|
|
# Tests:
|
|
|
|
Ecstatic has a fairly extensive test suite. You can run it with:
|
|
|
|
```sh
|
|
$ npm test
|
|
```
|
|
|
|
# Contribute:
|
|
|
|
Without outside contributions, ecstatic would wither and die! Before
|
|
contributing, take a quick look at the contributing guidelines in
|
|
[./CONTRIBUTING.md](./CONTRIBUTING.md) . They're relatively painless, I promise.
|
|
|
|
# License:
|
|
|
|
MIT. See LICENSE.txt. For contributors, see CONTRIBUTORS.md
|