Awesome
@koa/send
Koa static file serving middleware.
Notice: We recommend using
@koa/send
for installation, as bothkoa-send
and@koa/send
refer to the same module. However, in our next major versions bumps, we will deprecatekoa-send
and only maintain the module under@koa/send
.
Install
$ npm i @koa/send
Options
maxage
Browser cache max-age in milliseconds. (defaults to0
).immutable
Tell the browser the resource is immutable and can be cached indefinitely. (defaults tofalse
).hidden
Allow transfer of hidden files. (defaults tofalse
).root
Root directory to restrict file access.index
Name of the index file to serve automatically when visiting the root location. (defaults to none).gzip
Try to serve the gzipped version of a file automatically whengzip
is supported by a client and if the requested file with.gz
extension exists. (defaults totrue
).brotli
Try to serve the brotli version of a file automatically whenbrotli
is supported by a client and if the requested file with.br
extension exists. (defaults totrue
).format
If notfalse
(defaults totrue
), format the path to serve static file servers and not require a trailing slash for directories, so that you can do both/directory
and/directory/
.setHeaders
Function to set custom headers on response.extensions
Try to match extensions from passed array to search for file when no extension is sufficed in URL. First found is served. (defaults tofalse
)
Root path
Note that root
is required, defaults to ''
and will be resolved,
removing the leading /
to make the path relative and this
path must not contain "..", protecting developers from
concatenating user input. If you plan on serving files based on
user input supply a root
directory from which to serve from.
For example to serve files from ./public
:
app.use(async (ctx) => {
await send(ctx, ctx.path, { root: __dirname + "/public" });
});
To serve developer specified files:
app.use(async (ctx) => {
await send(ctx, "path/to/my.js");
});
setHeaders
The function is called as fn(res, path, stats)
, where the arguments are:
res
: the response object.path
: the resolved file path that is being sent.stats
: the stats object of the file that is being sent.
You should only use the setHeaders
option when you wish to edit the Cache-Control
or Last-Modified
headers, because doing it before is useless (it's overwritten by send
), and doing it after is too late because the headers are already sent.
If you want to edit any other header, simply set them before calling send
.
Example
const send = require("@koa/send");
const Koa = require("koa");
const app = new Koa();
// $ GET /package.json
// $ GET /
app.use(async (ctx) => {
if ("/" == ctx.path) return (ctx.body = "Try GET /package.json");
await send(ctx, ctx.path);
});
app.listen(3000);
console.log("listening on port 3000");