Registry / web-framework / koa-static-server

koa-static-server

library1.5.2jsnpmunverified

Static file serving middleware for Koa with support for directory listing, URL rewriting, and custom index files. Current stable version is 1.5.2. This package provides a simple API for serving static assets in Koa applications, similar to koa-static but with built-in options for rootPath rewriting, notFoundFile fallback, gzip support, and index file customization. It is designed for Koa v1 and may not be compatible with Koa v2 without additional conversion middleware.

web-framework http-networking

npm install koa-static-server

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-STATIC-SERVER

koa-static-server

web-frameworkjavascriptv1.5.2

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.

serve

✓ const serve = require('koa-static-server')

✗ import { serve } from 'koa-static-server'

This package uses CommonJS exports; ESM import with named export is not supported.

default

✓ import serve from 'koa-static-server'

✗ const serve = require('koa-static-server').default

When using ESM, use default import; the module does not export .default.

serve (as middleware)

✓ app.use(serve({ rootDir: 'public' }))

✗ app.use(serve) // missing options

serve must be called with an options object to create middleware.

Sets up a Koa static server serving files from 'public' under '/static' with index file support, caching, and gzip.

const Koa = require('koa'); const serve = require('koa-static-server'); const app = new Koa(); app.use(serve({ rootDir: 'public', rootPath: '/static', index: 'index.html', maxage: 3600000, gzip: true, hidden: false })); app.listen(3000, () => { console.log('Server running on port 3000'); });

Debug

Known issues

gotchaThis package is designed for Koa v1. Using it with Koa v2 requires a converter like 'koa-convert' or 'koa-v1-middleware'. Direct use may cause errors.

fix

If using Koa v2, use 'koa-convert' to wrap the middleware: app.use(convert(serve({...})))

affects: >=1.0.0

gotchaThe 'rootPath' option rewrites the URL path. For example, serving rootDir 'web' with rootPath '/admin' means URLs under '/admin' map to files in 'web', not '/admin/web'.

fix

Set rootPath to the URL prefix you want, not the filesystem path.

affects: >=1.0.0

gotchaIf no 'index' file is found at the root, the middleware does not send a default response and may call through to downstream middleware. This can cause 404s if not handled.

fix

Set 'notFoundFile' option to a fallback file, or ensure an index file exists in rootDir.

affects: >=1.0.0

deprecatedThe package has not been updated since 2016 and may have unpatched vulnerabilities. Use 'koa-static' or 'koa-send' instead for modern Koa applications.

fix

Migrate to 'koa-static' (v5+) for Koa v2 support and active maintenance.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: serve is not a function

Import error: using ESM named import instead of default import or require.

fix

Use default import: import serve from 'koa-static-server'

Error: Cannot find module 'koa'

Missing peer dependency 'koa'. This module requires 'koa' to be installed.

fix

Install koa: npm install koa

TypeError: app.use() requires a middleware function

Passing serve instead of serve() with options. serve is a factory function, not middleware.

fix

Use app.use(serve({ rootDir: 'public' }))

Upgrade

Version history

1.5.2latest on npm

Audit

Dependencies

koarequiredPeer dependency; used as middleware in Koa applications

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/pkoretic/koa-static-server ↗

packagehttps://www.npmjs.com/package/koa-static-server ↗