koa-classic-server

🚀 Production-ready Koa middleware for serving static files with Apache2-like directory listing, sortable columns, HTTP caching, template engine support, and enterprise-grade security.

![Tests]()

---

🎉 Version 2.X - Production-Ready Release

The 2.X series brings major performance improvements, enhanced security, and powerful new features while maintaining full backward compatibility.

$3

✅ URL Rewriting Support - Compatible with i18n and routing middleware via useOriginalUrl option
✅ Improved Caching Controls - Clear browserCacheEnabled and browserCacheMaxAge options
✅ Development-Friendly Defaults - Caching disabled by default for easier development
✅ Production Optimized - Enable caching in production for 80-95% bandwidth reduction
✅ Sortable Directory Columns - Click Name/Type/Size to sort (Apache2-like)
✅ File Size Display - Human-readable file sizes (B, KB, MB, GB, TB)
✅ HTTP Caching - ETag and Last-Modified headers with 304 responses
✅ Async/Await - Non-blocking I/O for high performance
✅ Performance Optimized - 50-70% faster directory listings
✅ Enhanced Index Option - Array format with RegExp support
✅ Template Engine Support - EJS, Pug, Handlebars, Nunjucks, and more
✅ Enterprise Security - Path traversal, XSS, race condition protection
✅ Comprehensive Testing - 197 tests passing with extensive coverage
✅ Complete Documentation - Detailed guides and examples

See full changelog →

---

Features

koa-classic-server is a high-performance middleware for serving static files with Apache2-like behavior, making file browsing intuitive and powerful.

$3

- 🗂️ Apache2-like Directory Listing - Sortable columns (Name, Type, Size)
- 📄 Static File Serving - Automatic MIME type detection with streaming
- 📊 Sortable Columns - Click headers to sort ascending/descending
- 📏 File Sizes - Human-readable display (B, KB, MB, GB, TB)
- ⚡ HTTP Caching - ETag, Last-Modified, 304 responses
- 🎨 Template Engine Support - EJS, Pug, Handlebars, Nunjucks, etc.
- 🔒 Enterprise Security - Path traversal, XSS, race condition protection
- ⚙️ Highly Configurable - URL prefixes, reserved paths, index files
- 🚀 High Performance - Async/await, non-blocking I/O, optimized algorithms
- 🧪 Well-Tested - 153 passing tests with comprehensive coverage
- 📦 Dual Module Support - CommonJS and ES Modules

---

Installation

``bash
npm install koa-classic-server
`

Requirements:
- Node.js >= 12.0.0
- Koa >= 2.0.0

---

Quick Start

$3

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

const app = new Koa();

// Serve files from "public" directory
app.use(koaClassicServer(__dirname + '/public'));

app.listen(3000);
console.log('Server running on http://localhost:3000');
`

$3

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

const app = new Koa();

app.use(koaClassicServer(__dirname + '/public', {
showDirContents: true,
index: ['index.html', 'index.htm'],
urlPrefix: '/static',
browserCacheMaxAge: 3600,
browserCacheEnabled: true
}));

app.listen(3000);
`

---

Complete Usage Guide

$3

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

// ES Modules
import koaClassicServer from 'koa-classic-server';
`

$3

Serve static files from a directory:

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

const app = new Koa();

app.use(koaClassicServer(__dirname + '/public', {
showDirContents: true,
index: ['index.html']
}));

app.listen(3000);
`

What it does:
- Serves files from /public directory
- Shows directory listing when accessing folders
- Looks for index.html in directories
- Sortable columns (Name, Type, Size)
- File sizes displayed in human-readable format

$3

Serve files under a specific URL path:

`javascript
app.use(koaClassicServer(__dirname + '/assets', {
urlPrefix: '/static',
showDirContents: true
}));
`

Result:
- http://localhost:3000/static/image.png → serves /assets/image.png
- http://localhost:3000/static/ → shows /assets directory listing

$3

Protect specific directories from being accessed:

`javascript
app.use(koaClassicServer(__dirname + '/www', {
urlsReserved: ['/admin', '/config', '/.git', '/node_modules']
}));
`

Result:
- /admin/* → passed to next middleware (not served)
- /config/* → protected
- Other paths → served normally

$3

Dynamically render templates with data:

`javascript
const ejs = require('ejs');

app.use(koaClassicServer(__dirname + '/views', {
template: {
ext: ['ejs', 'html.ejs'],
render: async (ctx, next, filePath) => {
const data = {
title: 'My App',
user: ctx.state.user || { name: 'Guest' },
items: ['Item 1', 'Item 2', 'Item 3'],
timestamp: new Date().toISOString()
};

ctx.body = await ejs.renderFile(filePath, data);
ctx.type = 'text/html';
}
}
}));
`

Template example (views/dashboard.ejs):
`html








Welcome, <%= user.name %>!

<% items.forEach(item => { %>

• <%= item %>

<% }); %>

Generated at: <%= timestamp %>

`

See complete guide: Template Engine Documentation →

$3

Enable aggressive caching for static files:

`javascript
app.use(koaClassicServer(__dirname + '/public', {
browserCacheEnabled: true, // Enable ETag and Last-Modified
browserCacheMaxAge: 86400, // Cache for 24 hours (in seconds)
}));
`

⚠️ Important: Production Recommendation

The default value for browserCacheEnabled is false to facilitate development (where you want changes to be immediately visible). For production environments, it is strongly recommended to set browserCacheEnabled: true to benefit from:

- 80-95% bandwidth reduction
- 304 Not Modified responses for unchanged files
- Faster page loads for returning visitors
- Reduced server load

See details: HTTP Caching Optimization →

$3

Search for multiple index files with custom order:

`javascript
app.use(koaClassicServer(__dirname + '/public', {
index: [
'index.html', // First priority
'index.htm', // Second priority
/index\.[eE][jJ][sS]/, // Third: index.ejs (case-insensitive)
'default.html' // Last priority
]
}));
`

See details: Index Option Priority →

$3

Real-world configuration for production:

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

const app = new Koa();

// Serve static assets with caching
app.use(koaClassicServer(path.join(__dirname, 'public'), {
method: ['GET', 'HEAD'],
showDirContents: false, // Disable directory listing in production
index: ['index.html', 'index.htm'],
urlPrefix: '/assets',
urlsReserved: ['/admin', '/api', '/.git'],
browserCacheEnabled: true,
browserCacheMaxAge: 86400, // 24 hours
}));

// Serve dynamic templates
app.use(koaClassicServer(path.join(__dirname, 'views'), {
showDirContents: false,
template: {
ext: ['ejs'],
render: async (ctx, next, filePath) => {
const data = {
env: process.env.NODE_ENV,
user: ctx.state.user,
config: ctx.state.config
};

try {
ctx.body = await ejs.renderFile(filePath, data);
ctx.type = 'text/html';
} catch (error) {
console.error('Template error:', error);
ctx.status = 500;
ctx.body = 'Internal Server Error';
}
}
}
}));

app.listen(3000);
`

---

API Reference

$3

Creates a Koa middleware for serving static files.

Parameters:

- rootDir (String, required): Absolute path to the directory containing files
- options (Object, optional): Configuration options

Returns: Koa middleware function

$3

`javascript
{
// HTTP methods allowed (default: ['GET'])
method: ['GET', 'HEAD'],

// Show directory contents (default: true)
showDirContents: true,

// Index file configuration
// Array format (recommended):
// - Strings: exact matches ['index.html', 'default.html']
// - RegExp: pattern matches [/index\.html/i]
// - Mixed: ['index.html', /INDEX\.HTM/i]
// Priority determined by array order (first match wins)
// See docs/INDEX_OPTION_PRIORITY.md for details
index: ['index.html', 'index.htm'],

// URL path prefix (default: '')
// Files served under this prefix
urlPrefix: '/static',

// Reserved paths (default: [])
// First-level directories passed to next middleware
urlsReserved: ['/admin', '/api', '/.git'],

// Template engine configuration
template: {
// Template rendering function
render: async (ctx, next, filePath) => {
// Your rendering logic
ctx.body = await yourEngine.render(filePath, data);
},

// File extensions to process
ext: ['ejs', 'pug', 'hbs']
},

// Browser HTTP caching configuration
// NOTE: Default is false for development. Set to true in production for better performance!
browserCacheEnabled: false, // Enable ETag & Last-Modified (default: false)
browserCacheMaxAge: 3600, // Cache-Control max-age in seconds (default: 3600 = 1 hour)

// URL resolution
useOriginalUrl: true, // Use ctx.originalUrl (default) or ctx.url
// Set false for URL rewriting middleware (i18n, routing)

// DEPRECATED (use new names above):
// enableCaching: use browserCacheEnabled instead
// cacheMaxAge: use browserCacheMaxAge instead
}
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| method | Array | ['GET'] | Allowed HTTP methods |
| showDirContents | Boolean | true | Show directory listing |
| index | Array/String | [] | Index file patterns (array format recommended) |
| urlPrefix | String | '' | URL path prefix |
| urlsReserved | Array | [] | Reserved directory paths (first-level only) |
| template.render | Function | undefined | Template rendering function |
| template.ext | Array | [] | Extensions for template rendering |
| browserCacheEnabled | Boolean | false | Enable browser HTTP caching headers (recommended: true in production) |
| browserCacheMaxAge | Number | 3600 | Browser cache duration in seconds |
| useOriginalUrl | Boolean | true | Use ctx.originalUrl (default) or ctx.url for URL resolution |
| ~~enableCaching~~ | Boolean | false | DEPRECATED: Use browserCacheEnabled instead |
| ~~cacheMaxAge~~ | Number | 3600 | DEPRECATED: Use browserCacheMaxAge instead |

#### useOriginalUrl (Boolean, default: true)

Controls which URL property is used for file resolution:
- true (default): Uses ctx.originalUrl (immutable, reflects the original request)
- false: Uses ctx.url (mutable, can be modified by middleware)

When to use false:

Set useOriginalUrl: false when using URL rewriting middleware such as i18n routers or path rewriters that modify ctx.url. This allows koa-classic-server to serve files based on the rewritten URL instead of the original request URL.

Example with i18n middleware:

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

const app = new Koa();

// i18n middleware that rewrites URLs
app.use(async (ctx, next) => {
if (ctx.path.match(/^\/it\//)) {
ctx.url = ctx.path.replace(/^\/it/, ''); // /it/page.html → /page.html
}
await next();
});

// Serve files using rewritten URL
app.use(koaClassicServer(__dirname + '/www', {
useOriginalUrl: false // Use ctx.url (rewritten) instead of ctx.originalUrl
}));

app.listen(3000);
`

How it works:
- Request: GET /it/page.html
- ctx.originalUrl: /it/page.html (unchanged)
- ctx.url: /page.html (rewritten by middleware)
- With useOriginalUrl: false: Server looks for /www/page.html ✅
- With useOriginalUrl: true (default): Server looks for /www/it/page.html ❌ 404

---

Directory Listing Features

$3

Click on column headers to sort:

- Name - Alphabetical sorting (A-Z or Z-A)
- Type - Sort by MIME type (directories always first)
- Size - Sort by file size (directories always first)

Visual indicators:
- ↑ - Ascending order
- ↓ - Descending order

$3

Human-readable format:
- 1.5 KB - Kilobytes
- 2.3 MB - Megabytes
- 1.2 GB - Gigabytes
- - - Directories (no size)

$3

- Click folder name - Enter directory
- Click file name - Download/view file
- Parent Directory - Go up one level

---

Security

$3

koa-classic-server includes enterprise-grade security:

#### 1. Path Traversal Protection

Prevents access to files outside rootDir:

`javascript
// ❌ Blocked requests
GET /../../../etc/passwd → 403 Forbidden
GET /../config/database.yml → 403 Forbidden
GET /%2e%2e%2fpackage.json → 403 Forbidden
`

#### 2. XSS Protection

All filenames and paths are HTML-escaped:

`javascript
// Malicious filename: .txt
// Displayed as: <script>alert('xss')</script>.txt
// ✅ Safe - script doesn't execute
`

#### 3. Reserved URLs

Protect sensitive directories:

`javascript
app.use(koaClassicServer(__dirname, {
urlsReserved: ['/admin', '/config', '/.git', '/node_modules']
}));
`

#### 4. Race Condition Protection

File access is verified before streaming:

`javascript
// File deleted between check and access?
// ✅ Returns 404 instead of crashing
`

See full security audit: Security Tests →

---

Performance

$3

Version 2.x includes major performance improvements:

- Async/Await - Non-blocking I/O, event loop never blocked
- Array Join - 30-40% less memory vs string concatenation
- HTTP Caching - 80-95% bandwidth reduction
- Single stat() Call - No double file system access
- Streaming - Large files streamed efficiently

$3

Performance results on directory with 1,000 files:

`
Before (v1.x): ~350ms per request
After (v2.x): ~190ms per request
Improvement: 46% faster
`

See detailed benchmarks: Performance Analysis →

---

Testing

Run the comprehensive test suite:

`bash


Run all tests

npm test

Run security tests only

npm run test:security

Run performance benchmarks

npm run test:performance
`

Test Coverage:
- ✅ 197 tests passing
- ✅ Security tests (path traversal, XSS, race conditions)
- ✅ EJS template integration tests
- ✅ Index option tests (strings, arrays, RegExp)
- ✅ Performance benchmarks
- ✅ Directory sorting tests

---

Complete Documentation

$3

- DOCUMENTATION.md - Complete API reference and usage guide
- FLOW_DIAGRAM.md - Visual flow diagrams and code execution paths
- CHANGELOG.md - Version history and release notes

$3

- TEMPLATE_ENGINE_GUIDE.md - Complete guide to template engine integration
- Progressive examples (simple to enterprise)
- EJS, Pug, Handlebars, Nunjucks support
- Best practices and troubleshooting

$3

- INDEX_OPTION_PRIORITY.md - Detailed priority behavior for index option
- String vs Array vs RegExp formats
- Priority order examples
- Migration guide from v1.x

- EXAMPLES_INDEX_OPTION.md - 10 practical examples of index option with RegExp
- Case-insensitive matching
- Multiple extensions
- Complex patterns

$3

- PERFORMANCE_ANALYSIS.md - Performance optimization analysis
- Before/after comparisons
- Memory usage analysis
- Bottleneck identification

- PERFORMANCE_COMPARISON.md - Detailed performance benchmarks
- Request latency
- Throughput metrics
- Concurrent request handling

- OPTIMIZATION_HTTP_CACHING.md - HTTP caching implementation details
- ETag generation
- Last-Modified headers
- 304 Not Modified responses

- BENCHMARKS.md - Benchmark results and methodology

$3

- CODE_REVIEW.md - Code quality analysis and review
- Security audit
- Best practices
- Standardization improvements

- DEBUG_REPORT.md - Known limitations and debugging info
- Reserved URLs behavior
- Edge cases
- Troubleshooting tips

---

Migration Guide

$3

Breaking Changes:
- index option: String format deprecated (still works), use array format

Migration:

`javascript
// v1.x (deprecated)
{
index: 'index.html'
}

// v2.x (recommended)
{
index: ['index.html']
}
`

New Features:
- HTTP caching (enabled by default)
- Sortable directory columns
- File size display
- Enhanced index option with RegExp

See full migration guide: CHANGELOG.md

---

Examples

$3

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

const app = new Koa();
app.use(koaClassicServer(__dirname + '/public'));
app.listen(3000);
`

$3

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

const app = new Koa();

// Serve static assets
app.use(koaClassicServer(__dirname + '/public', {
urlPrefix: '/static',
showDirContents: false
}));

// Serve user uploads
app.use(koaClassicServer(__dirname + '/uploads', {
urlPrefix: '/files',
showDirContents: true
}));

app.listen(3000);
`

$3

`javascript
const Koa = require('koa');
const koaClassicServer = require('koa-classic-server');
const ejs = require('ejs');

const app = new Koa();

// Development mode - show directories
app.use(koaClassicServer(__dirname + '/src', {
showDirContents: true,
template: {
ext: ['ejs'],
render: async (ctx, next, filePath) => {
ctx.body = await ejs.renderFile(filePath, {
dev: true,
timestamp: Date.now()
});
ctx.type = 'text/html';
}
}
}));

app.listen(3000);
`

---

Troubleshooting

$3

Issue: 404 errors for all files

Check that rootDir is an absolute path:

`javascript
// ❌ Wrong (relative path)
koaClassicServer('./public')

// ✅ Correct (absolute path)
koaClassicServer(__dirname + '/public')
koaClassicServer(path.join(__dirname, 'public'))
`

Issue: Reserved URLs not working

Reserved URLs only work for first-level directories:

`javascript
urlsReserved: ['/admin'] // ✅ Blocks /admin/*
urlsReserved: ['/admin/users'] // ❌ Doesn't work (nested)
`

Issue: Directory sorting not working

Make sure you're accessing directories without query params initially. The sorting is applied when you click headers.

See full troubleshooting: DEBUG_REPORT.md

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (npm test`)
5. Submit a pull request

---

Known Limitations

- Reserved URLs only work for first-level directories
- Template rendering is synchronous per request

See DEBUG_REPORT.md for technical details.

---

License

MIT License - see LICENSE file for details

---

Author

Italo Paesano

---

Links

- npm Package - Official npm package
- GitHub Repository - Source code
- Issue Tracker - Report bugs
- Full Documentation - Complete reference

---

Changelog

See CHANGELOG.md for version history.

---

⚠️ Security Notice: Always use the latest version for security updates and bug fixes.