Registry / devops / koa-static-resolver

koa-static-resolver

library1.0.6jsnpmunverified

Koa middleware for serving static files with support for multiple directories, default index files, path replacement, caching, live reload injection, and on-the-fly gzip compression. Currently at v1.0.6, stable with TypeScript types included. Differentiators: built-in livereload script injection, flexible include/exclude patterns with RegExp support, path rewriting, and configurable gzip types — all in a single lightweight middleware.

devops

npm install koa-static-resolver

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOA-STATIC-RESOLVE

koa-static-resolver

devopsjavascriptv1.0.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import KSR from 'koa-static-resolver'

✗ const KSR = require('koa-static-resolver')

ESM only since v1. The default export is the middleware factory. CommonJS require still works in Node but TypeScript may warn without esModuleInterop.

KSR

✓ import KSR from 'koa-static-resolver'

✗ import { KSR } from 'koa-static-resolver'

The package exports a single default export. Named import will result in undefined.

type Options

✓ import type { Options } from 'koa-static-resolver'

✗ import { Options } from 'koa-static-resolver'

Type-only import to avoid bundling runtime value. The Options type is used for the configuration object.

Create a Koa server with static file serving, caching, and gzip compression.

import Koa from 'koa'; import KSR from 'koa-static-resolver'; const app = new Koa(); app.use(KSR({ dirs: ['./public', '../shared-assets'], defaultIndex: 'index.html', cache: {}, maxAge: 3600, gzip: true, gzipMinLength: 1024, gzipTypes: ['.html', '.css', '.js'], })); app.listen(3000); console.log('Server running on http://localhost:3000');

Debug

Known issues

deprecatedThe `livereload` option string is directly injected as raw script tag — potential XSS if source directory contains user-controlled HTML.

fix

Sanitize livereload scripts or avoid using with untrusted HTML files.

affects: >=1.0.0

gotchaThe `cache` option must be an object (e.g., `{}`). Setting it to `false` or `undefined` will not disable caching correctly — it defaults to disabled anyway.

fix

Use `cache: {}` to enable in-memory cache, or omit to disable.

affects: >=1.0.0

gotchaIf `maxAge` is set to 0, the cache behavior is inconsistent — may still serve stale files.

fix

Upgrade to v1.0.3 or later where the bug was fixed.

affects: 1.0.0 - 1.0.2

gotchaThe `dirs` option paths are resolved relative to the current working directory, not the module location. This can lead to directory not found errors.

fix

Use absolute paths or `path.resolve(__dirname, dirname)` to avoid ambiguity.

affects: >=1.0.0

gotchaThe module uses `koa-send` internally but does not re-export it; you cannot control `koa-send` options directly.

fix

If you need fine-grained control over file serving, consider using `koa-send` directly or another middleware.

affects: >=1.0.0

gotchaTypeScript definitions are included but may be incomplete for options like `replace` key-value pairs.

fix

Cast configuration object to `any` if type errors occur: `KSR(options as any)`.

affects: >=1.0.5

Errors

Common errors & fixes

TypeError: KSR is not a function

Using named import instead of default import.

fix

Use `import KSR from 'koa-static-resolver'` (no curly braces).

Error: ENOENT: no such file or directory, stat '/path/to/static'

The `dirs` path is relative and doesn't exist from the current working directory.

fix

Use absolute paths: `dirs: [path.resolve(__dirname, 'static')]`.

Module not found: Can't resolve 'koa-static-resolver'

Package not installed or missing from node_modules.

fix

Run `npm install koa-static-resolver`.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cenfun/koa-static-resolver ↗

packagekoa-static-resolver ↗

homepagehttps://github.com/cenfun/koa-static-resolver#readme ↗