koa-classic-server

Serve a directory of files over HTTP from Koa — with classic, sortable directory listings, clean URLs, automatic compression, and HTTP caching. In the spirit of a traditional web server, but intentionally its own thing.

One rule drives every default:

If a file exists under rootDir, GET on its path returns it. A directory without an index file shows a listing of every visible entry.

Defaults are transparent — the middleware never hides or restricts your files unless you ask. Hardening is opt-in.

Install

npm install koa-classic-server

Requires Node ≥ 20 and Koa ≥ 3.1.2. (Koa 2 and Node 18 were supported through v4.x; both were dropped in v5.0.0.)

Import

Ships as both CommonJS and ES modules via conditional exports — use whichever your project prefers:

// CommonJS
const koaClassicServer = require('koa-classic-server');

// ES modules
import koaClassicServer from 'koa-classic-server';

The examples below use CommonJS; they work identically with the ESM import.

Quick start

const Koa = require('koa');
const path = require('path');
const koaClassicServer = require('koa-classic-server');

const app = new Koa();
app.use(koaClassicServer(path.join(__dirname, 'public')));
app.listen(3000);
// → serves ./public, with a browsable listing when there's no index file

rootDir must be an absolute path — use path.join(__dirname, ...).

Examples

Each example is self-contained. Copy, adjust the path, run.

Serve a site with an index file

app.use(koaClassicServer(path.join(__dirname, 'public'), {
  index: ['index.html'],   // GET /  → public/index.html
}));

A browsable, sortable, paginated listing

app.use(koaClassicServer(path.join(__dirname, 'uploads'), {
  dirListing: {
    enabled:        true,
    entriesPerPage: 100,   // paginate with ?page=N once a folder exceeds this
  },
}));
// Click Name / Type / Size to sort; sort order is kept across pages.

Clean URLs with a template engine (EJS)

const ejs = require('ejs');

app.use(koaClassicServer(path.join(__dirname, 'views'), {
  hideExtension: { ext: '.ejs' },   // GET /about → views/about.ejs ; GET /about.ejs → 301 /about
  template: {
    ext: ['.ejs'],   // leading dot optional since v5: '.ejs' (preferred) ≡ 'ejs'
    // signature: (ctx, next, filePath, rawBuffer, signal)
    render: async (ctx, next, filePath, rawBuffer, signal) => {
      ctx.type = 'html';
      ctx.body = await ejs.renderFile(filePath, { user: ctx.state.user }, { signal });
    },
  },
}));

rawBuffer (4th arg) is the file's bytes if already in cache (may be null) and is read-only. signal (5th arg) aborts on timeout and on client disconnect — forward it to your I/O.

HTTP caching (production)

app.use(koaClassicServer(path.join(__dirname, 'public'), {
  browserCacheEnabled: true,    // ETag + Last-Modified, and 304 on revalidation
  browserCacheMaxAge:  86400,   // Cache-Control: max-age=86400 (24h)
}));

Off by default (development-friendly). Conditional requests are fully handled: If-None-Match (lists, *, weak tags), If-Modified-Since, and Range (206) all behave per the HTTP spec.

Compression — automatic

Brotli/gzip are on by default for compressible types, negotiated from Accept-Encoding and cached server-side. Nothing to configure. To tune or disable:

app.use(koaClassicServer(root, {
  compression: {
    encodings:   ['br', 'gzip'], // server preference order; [] disables
    minFileSize: 1024,           // don't compress tiny files
  },
}));

// or turn it off entirely:
app.use(koaClassicServer(root, { compression: false }));

To size compression quality and the server-side caches to your host's RAM and CPU (small VPS, weak CPU, big dedicated box, behind a CDN), see the Performance Tuning Guide — it includes copy-paste profiles.

Hide sensitive files

Dot-files are served by default (the operator's directory is the source of truth). For a public deployment, hide them explicitly:

app.use(koaClassicServer(path.join(__dirname, 'www'), {
  hidden: {
    dotFiles: { default: 'hidden', whitelist: ['.well-known'] }, // keep ACME/Let's Encrypt working
    dotDirs:  { default: 'hidden', whitelist: ['.well-known'] },
    alwaysHide: ['*.key', /secret/i],                            // path-aware patterns
  },
}));
// .env, .git/config, *.key → 404

Custom error pages

Branded 404/500/504 pages from self-contained .html files (v4.2+). Keep them outside rootDir so they are not themselves reachable via URL; edit them anytime — changes are picked up without a restart, and an unreadable file falls back to the built-in page:

app.use(koaClassicServer(path.join(__dirname, 'www'), {
  errorPages: {
    404: path.join(__dirname, 'errors', '404.html'),
    500: path.join(__dirname, 'errors', '500.html'),
  },
}));

One rule: each page must be a single self-contained file (inline CSS, no external css/js/img references). Custom pages are served without the built-in pages' Content-Security-Policy, so an external reference would really load.

Mount under a prefix, pass through some routes

app.use(koaClassicServer(path.join(__dirname, 'public'), {
  urlPrefix:    '/static',              // GET /static/app.js → public/app.js
  urlsReserved: ['/api', '/admin'],     // first-level paths handed to the next middleware
}));

Serve several directories

Mount it once per directory, each under its own urlPrefix — a request outside a mount's prefix falls through to the next:

// Assets under /static, no listing
app.use(koaClassicServer(path.join(__dirname, 'public'), {
  urlPrefix: '/static',
  dirListing: { enabled: false },
}));

// Uploads under /files, browsable
app.use(koaClassicServer(path.join(__dirname, 'uploads'), {
  urlPrefix: '/files',
  dirListing: { enabled: true },
}));

Allow more methods

GET and HEAD are accepted by default — HEAD needs no opt-in, since RFC 9110 §9.1 makes the pair the minimum a general-purpose server must support. Any other verb falls through to the next middleware (it is not answered with 405, so a downstream router can handle it):

app.use(koaClassicServer(root, {
  method: ['GET', 'HEAD', 'POST'],   // POST served exactly like GET
}));

Dropping HEAD (method: ['GET']) is honored, but produces an RFC 9110 §9.1 non-conformant server: HEAD then answers 404 on files GET serves with 200. See the Security Hardening Guide §3.7.

Behind a URL rewriter (i18n, routing)

When an upstream middleware mutates ctx.url, tell the server to resolve against the rewritten URL:

app.use(async (ctx, next) => {
  if (ctx.path.startsWith('/it/')) ctx.url = ctx.url.replace(/^\/it/, ''); // /it/page → /page
  await next();
});

app.use(koaClassicServer(path.join(__dirname, 'www'), {
  useOriginalUrl: false,   // resolve ctx.url (rewritten) instead of ctx.originalUrl
}));

Keep symlinks inside `rootDir`

If rootDir holds files writable by untrusted parties (uploads, multi-tenant), stop a planted symlink from escaping the served tree:

app.use(koaClassicServer(root, {
  symlinks: 'follow-within-root',   // a link resolving outside rootDir → 404
}));

A production-shaped setup

const pino = require('pino')({ level: 'info' });

app.use(koaClassicServer(path.join(__dirname, 'public'), {
  index:               ['index.html'],
  dirListing:          { enabled: process.env.NODE_ENV !== 'production' },
  browserCacheEnabled: true,
  browserCacheMaxAge:  86400,
  logger:              pino,   // any { error, warn, info, debug } object (Pino/Winston/Bunyan/console)
  hidden: {
    dotFiles: { default: 'hidden', whitelist: ['.well-known'] },
    dotDirs:  { default: 'hidden', whitelist: ['.well-known'] },
  },
}));

What's new in v5

v5.0.0 is the configuration-correctness release: config mistakes that used to misbehave silently at request time now fail fast at startup, and the two extension options finally share one coherent, forgiving syntax.

hideExtension.redirect is validated at startup. Accepted values are the real redirect codes — 300, 301, 302, 303, 305, 307, 308 — and anything else throws at factory time with the valid list in the message. Until v4 a wrong value failed silently in production: a non-redirect integer (200, 404, 999, …) was quietly sent as 302, and a non-integer value produced a 500 on every redirect.
The leading dot is optional in template.ext and hideExtension.ext — '.ejs' and 'ejs' are equivalent everywhere; the preferred, documented form is '.ejs'. This also fixes a long-standing trap: a dotted template.ext entry (['.ejs']) used to never match, so the render never ran and the template source was served raw. It now works as intended.
template.ext matches by suffix (as hideExtension.ext always did), so compound extensions are supported: ['.html.ejs'] targets only *.html.ejs files. Entries that cannot name a suffix (empty, '.', non-string) are dropped with a one-time warning.
A non-function template.render now warns (one-time) instead of silently disabling template rendering.

The v4 highlights — canonical trailing slash, bounded compression with streamed-output caching, configurable compression quality, custom error pages — are all still here. Full details in the changelog.

Options

Defaults shown; every option is optional.

koaClassicServer(rootDir, {
  method: ['GET', 'HEAD'],               // allowed HTTP methods (upper-cased; other verbs → next())

  dirListing: {
    enabled:        true,                // render a listing when no index matches (false → 404)
    entriesPerPage: 100,                 // paginate above this (0 = off)
    maxEntries:     10000,               // safety-net cap on entries rendered (0 = off)
    trailingSlash:  true,                // v4: /dir → 301 /dir/, /file/ → 404
  },

  index: [],                             // e.g. ['index.html']; strings and/or RegExp

  urlPrefix:    '',                      // e.g. '/static' (leading slash, no trailing)
  urlsReserved: [],                      // e.g. ['/api'] — first-level, passed to next()
  useOriginalUrl: true,                  // false when an upstream middleware rewrites ctx.url

  hideExtension: {                       // clean URLs
    ext:      '.ejs',                    // suffix to hide — leading dot optional (v5), compound ('.tar.gz') ok
    redirect: 301,                       // v5: must be 300|301|302|303|305|307|308, else throws at startup
  },

  hidden: {                              // everything visible by default
    dotFiles: { default: 'visible', whitelist: [], blacklist: [] },
    dotDirs:  { default: 'visible', whitelist: [], blacklist: [] },
    alwaysHide: [],                      // glob strings or RegExp, path-aware
  },

  browserCacheEnabled: false,            // ETag/Last-Modified/304 (recommended true in prod)
  browserCacheMaxAge:  3600,             // Cache-Control max-age (seconds)

  compression: {                         // or `compression: false`
    enabled:     true,
    encodings:   ['br', 'gzip'],
    minFileSize: 1024,
    maxFileSize: 10485760,               // 10 MB buffered-path cap (false = no cap)
    mimeTypes:   [],                     // override the compressible-type list
    buffered:  { brotliQuality: 11, gzipLevel: 9 },  // v4.3: quality when compressing once, then caching
    streaming: { brotliQuality: 4,  gzipLevel: 6 },  // v4.3: quality when compressing per request (above maxFileSize)
  },

  serverCache: {                         // in-memory server-side caches
    rawFile: {                           // cache raw file buffers (skip disk reads)
      enabled:      false,
      maxSize:      52428800,            // total RAM cap, bytes (50 MB)
      maxFileSize:  1048576,             // larger files are never cached, bytes (1 MB)
      maxAge:       0,                   // ms before an entry counts as stale (0 = off)
      warnInterval: 60000,               // ms between "maxSize reached" warnings (0 = always, false = never)
    },
    compressedFile: {                    // cache br/gzip responses (compress once)
      enabled:      true,
      maxSize:      104857600,           // total RAM cap, bytes (100 MB)
      maxEntrySize: undefined,           // v4.3: per-entry cap on the compressed output, bytes
                                         //   default: maxSize / 4; false = no per-entry cap;
                                         //   oversized entries are served, just never cached
      maxAge:       0,                   // ms before an entry counts as stale (0 = off)
      warnInterval: 60000,               // ms between "maxSize reached" warnings (0 = always, false = never)
    },
  },

  symlinks: 'follow',                    // 'follow' | 'follow-within-root' | 'deny'
  staticSecurityHeaders: { nosniff: false }, // set nosniff on static responses

  errorPages: {                          // custom error pages (v4.2+); omitted → built-ins
    // 404: './errors/404.html',         // supported statuses: 404, 500, 504
    // 500: './errors/500.html',         // self-contained .html (inline CSS, no external refs)
    // 504: './errors/504.html',         // editable without a restart; unreadable → built-in
  },

  template: {
    ext: [],                             // e.g. ['.ejs'] — dot optional (v5); suffix match, so
                                         //   compound entries ('.html.ejs') target *.html.ejs only
    renderTimeout: 30000,                // ms; on timeout the request fails closed (0 = off)
    render: async (ctx, next, filePath, rawBuffer, signal) => { /* ... */ },
  },

  logger: console,                       // { error, warn, info, debug }
})

Full per-option reference: docs/DOCUMENTATION.md.

Security

Defaults are transparent, so hardening is a deliberate opt-in. The single source of truth is the Security Hardening Guide — threat models, per-topic recommendations, per-profile checklists, and a copy-paste maximally-hardened config.

Built in and always on: path-traversal defense (traversal / encoded / null-byte / boundary → 404 or 400, never a leak), HTML-escaping + hash-based CSP on the listing, security headers on generated pages, and last-resort error containment. Host validation and static-file CSP/HSTS are intentionally left to a reverse proxy or an upstream middleware.

Migrating from v4

If your hideExtension.redirect is already a real redirect code (or unset) and your template.ext entries are dot-less, v5 changes nothing — everything below is either a config bug surfacing earlier or a previously broken form starting to work.

What	v4	v5
`hideExtension.redirect: 200` (any non-redirect integer)	silently sent as `302`	throws at startup — valid: `300, 301, 302, 303, 305, 307, 308`
`hideExtension.redirect: '301'` (non-integer)	500 on every redirect	throws at startup
`template.ext: ['.ejs']` (with dot)	never matched — template source served raw	renders — `'.ejs'` ≡ `'ejs'`, dotted form preferred
`template.ext: ['.html.ejs']` (compound)	never matched	targets `*.html.ejs` files only
`hideExtension.ext: 'ejs'` (no dot)	worked, with a warning	works — warning gone, both forms legal
`template.render: <non-function>`	silently dropped (sources served raw)	one-time warning (startup error planned for v6)

The v3 → v4 notes (trailing slash, compression.maxFileSize, strict options validation) remain in the changelog.

Testing

npm test                 # full suite (lints first)
npm run test:ci          # suite without benchmarks — 1284 tests
npm run test:security    # security tests only
npm run test:performance # benchmarks

The suite includes fast-check property-based tests (__tests__/*.property.test.js) alongside the example-based ones. They are intentionally un-seeded; to replay a failure, see property-based-testing.md.

Docs

DOCUMENTATION.md — full API reference
SECURITY_HARDENING.md — hardening guide (canonical)
PERFORMANCE_TUNING.md — sizing caches & compression for your host's RAM/CPU
CHANGELOG.md — version history
TEMPLATE_ENGINE_GUIDE.md — EJS/Pug/Handlebars/Nunjucks

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
__tests__		__tests__
docs		docs
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
index.cjs		index.cjs
index.mjs		index.mjs
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository navigation

About

Repository files navigation

koa-classic-server

Install

Import

Quick start

Examples

Serve a site with an index file

A browsable, sortable, paginated listing

Clean URLs with a template engine (EJS)

HTTP caching (production)

Compression — automatic

Hide sensitive files

Custom error pages

Mount under a prefix, pass through some routes

Serve several directories

Allow more methods

Behind a URL rewriter (i18n, routing)

Keep symlinks inside `rootDir`

A production-shaped setup

What's new in v5

Options

Security

Migrating from v4

Testing

Docs

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

koa-classic-server

Install

Import

Quick start

Examples

Serve a site with an index file

A browsable, sortable, paginated listing

Clean URLs with a template engine (EJS)

HTTP caching (production)

Compression — automatic

Hide sensitive files

Custom error pages

Mount under a prefix, pass through some routes

Serve several directories

Allow more methods

Behind a URL rewriter (i18n, routing)

Keep symlinks inside rootDir

A production-shaped setup

What's new in v5

Options

Security

Migrating from v4

Testing

Docs

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Keep symlinks inside `rootDir`