Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

koa-static-cache

koajs126.3kMIT5.1.4TypeScript support: definitely-typed

Static cache for koa

koa, middleware, file, static, cache, gzip, sendfile

readme

Koa Static Cache

NPM version build status Test coverage David deps

Static server for koa.

Differences between this library and other libraries such as static:

  • There is no directory or index.html support.
  • You may optionally store the data in memory - it streams by default.
  • Caches the assets on initialization - you need to restart the process to update the assets.(can turn off with options.preload = false)
  • Uses MD5 hash sum as an ETag.
  • Uses .gz files if present on disk, like nginx gzip_static module

Installation

$ npm install koa-static-cache

API

staticCache(dir [, options] [, files])

var path = require('path')
var staticCache = require('koa-static-cache')

app.use(staticCache(path.join(__dirname, 'public'), {
  maxAge: 365 * 24 * 60 * 60
}))
  • dir (str) - the directory you wish to serve, priority than options.dir.
  • options.dir (str) - the directory you wish to serve, default to process.cwd.
  • options.maxAge (int) - cache control max age for the files, 0 by default.
  • options.cacheControl (str) - optional cache control header. Overrides options.maxAge.
  • options.buffer (bool) - store the files in memory instead of streaming from the filesystem on each request.
  • options.gzip (bool) - when request's accept-encoding include gzip, files will compressed by gzip.
  • options.usePrecompiledGzip (bool) - try use gzip files, loaded from disk, like nginx gzip_static
  • options.alias (obj) - object map of aliases. See below.
  • options.prefix (str) - the url prefix you wish to add, default to ''.
  • options.dynamic (bool) - dynamic load file which not cached on initialization.
  • options.filter (function | array) - filter files at init dir, for example - skip non build (source) files. If array set - allow only listed files
  • options.preload (bool) - caches the assets on initialization or not, default to true. always work together with options.dynamic.
  • options.files (obj) - optional files object. See below.
  • files (obj) - optional files object. See below.

    Aliases

For example, if you have this alias object:

{
  '/favicon.png': '/favicon-32.png'
}

Then requests to /favicon.png will actually return /favicon-32.png without redirects or anything. This is particularly important when serving favicons as you don't want to store duplicate images.

Files

You can pass in an optional files object. This allows you to do two things:

Combining directories into a single middleware

Instead of doing:

app.use(staticCache('/public/js'))
app.use(staticCache('/public/css'))

You can do this:

var files = {}

// Mount the middleware
app.use(staticCache('/public/js', {}, files))

// Add additional files
staticCache('/public/css', {}, files)

The benefit is that you'll have one less function added to the stack as well as doing one hash lookup instead of two.

Editing the files object

For example, if you want to change the max age of /package.json, you can do the following:

var files = {}

app.use(staticCache('/public', {
  maxAge: 60 * 60 * 24 * 365
}, files))

files['/package.json'].maxAge = 60 * 60 * 24 * 30

Using a LRU cache to avoid OOM when dynamic mode enabled

You can pass in a lru cache instance which has tow methods: get(key) and set(key, value).

var LRU = require('lru-cache')
var files = new LRU({ max: 1000 })

app.use(staticCache({
  dir: '/public',
  dynamic: true,
  files: files
}))

License

The MIT License (MIT)

Copyright (c) 2013 Jonathan Ong me@jongleberry.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

changelog

5.1.4 / 2020-08-03

fixes

5.1.3 / 2020-04-29

fixes

5.1.2 / 2018-02-06

others

5.1.1 / 2017-06-13

  • fix: only load file under options.dir (#67)

5.1.0 / 2017-06-01

  • feat: files support lru (#64)
  • Update mz (#61)

5.0.1 / 2017-04-19

  • Add node.js v7.6.0 support (#58)

5.0.0 / 2017-04-01

  • Support Koa 2 (#57)

4.0.0 / 2017-02-21

  • refactor: check prefix first to avoid calculate (#56)

3.2.0 / 2017-01-07

  • feat: support options.preload (#55)

3.1.7 / 2016-04-07

  • update mz to 2.4.0

3.1.6 / 2016-03-22

  • fix: don't catch downstream error

3.1.5 / 2016-03-02

  • fix: dynamic load file bug on windows platform

3.1.4 / 2016-01-04

  • bump deps
  • use mz

3.1.3 / 2015-11-26

  • Fix broken mtime comparison

3.1.2 / 2015-07-08

  • bugfix: error on dynamic files

3.1.1 / 2015-04-17

  • fix: options.prefix bug in windows, fixes #39

3.1.0 / 2015-03-28

  • Merge pull request #33 from AlexeyKhristov/gz

3.0.3 / 2015-03-28

  • fix problem, cache is not used in dynamic mode

3.0.2 / 2015-03-18

  • fix options.prefix bug in windows, fixes #36

3.0.1 / 2015-01-06

  • feat(dynamic): add dynamic option to support dynamic load
  • fix(dynamic): use stat to detect folder

3.0.0 / 2015-01-06

  • fix(test): typo
  • fix(buffer): keep the old logic of treat unbuffered file
  • feat: add opt.buffer false to serve file not cache at all
  • fix: support load file dynamic, close #30

2.0.2 / 2015-01-05

  • fix normalize bug in windows, fixes #29

2.0.1 / 2014-12-02

  • accept abnormal path, like: //index.html

2.0.0 / 2014-11-14

  • bump koa
  • only response GET and HEAD

1.2.0 / 2014-09-18

  • bump compressible and mime-types
  • decodeURI when use this.path as key to fetch value from files object

1.1.0 / 2014-07-16

  • replace mime by mime-types
  • remove onerror and destroy, let koa hanlde these stuff

1.0.10 / 2014-05-18

  • bump fs-readdir-recursive, fixed #14
  • fix bad argument handling, fixed #20
  • should not return gzip buffer when accept encoding not include gzip

1.0.9 / 2014-03-31

  • add url prefix option

1.0.8 / 2014-03-31

  • support options.dir, default to process.cwd()
  • add vary, check file's length when gzip
  • Ensure files can be gzipped via compressible.

1.0.7 / 2014-03-26

  • add options.gzip to control gzip, support stream's gzip
  • add gzip support for buffers

1.0.3 / 2014-01-14

  • update on-socket-error

1.0.0 / 2013-12-21

  • use yield* next