koa-classic-server 2.5.0 → 2.5.2

package/README.md

@@ -64,8 +64,8 @@ npm install koa-classic-server
 ```
 
 **Requirements:**
-- Node.js >= 12.0.0
-- Koa >= 2.0.0
+- Node.js >= 18.0.0
+- Koa >= 2.0.0 (Koa 3 requires >= 3.1.2)
 
 ---
 
@@ -264,7 +264,133 @@ app.use(koaClassicServer(__dirname + '/public', {
 
 > **Note**: This conflict resolution behavior differs from Apache/Nginx, where directories typically take priority over files with the same base name.
 
-### 7. With HTTP Caching
+### 7. URL Rewriting Support (useOriginalUrl)
+
+When using URL rewriting middleware (i18n, routing), set `useOriginalUrl: false` so koa-classic-server resolves files from the rewritten URL instead of the original one:
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// i18n middleware: strips language prefix and rewrites ctx.url
+app.use(async (ctx, next) => {
+  const langMatch = ctx.path.match(/^\/(it|en|fr|de|es)\//);
+  if (langMatch) {
+    ctx.state.lang = langMatch[1];       // Save language for templates
+    ctx.url = ctx.path.replace(/^\/(it|en|fr|de|es)/, '') + ctx.search;
+  }
+  await next();
+});
+
+// Serve files using the rewritten URL
+app.use(koaClassicServer(__dirname + '/public', {
+  useOriginalUrl: false  // Use ctx.url (rewritten) instead of ctx.originalUrl
+}));
+
+app.listen(3000);
+```
+
+**How it works:**
+
+| Request | `ctx.originalUrl` | `ctx.url` (rewritten) | File resolved |
+|---------|-------------------|----------------------|---------------|
+| `/it/page.html` | `/it/page.html` | `/page.html` | `public/page.html` |
+| `/en/page.html` | `/en/page.html` | `/page.html` | `public/page.html` |
+| `/page.html` | `/page.html` | `/page.html` | `public/page.html` |
+
+- With `useOriginalUrl: true` (default): the server would look for `public/it/page.html` (which doesn't exist)
+- With `useOriginalUrl: false`: the server looks for `public/page.html` (correct)
+
+### 8. Advanced hideExtension Scenarios
+
+#### Recommended file structure
+
+```
+views/
+├── index.ejs              ← / (home page)
+├── about.ejs              ← /about
+├── contact.ejs            ← /contact
+├── blog/
+│   ├── index.ejs          ← /blog/
+│   ├── first-post.ejs     ← /blog/first-post
+│   └── second-post.ejs    ← /blog/second-post
+├── docs/
+│   ├── index.ejs          ← /docs/
+│   ├── getting-started.ejs ← /docs/getting-started
+│   └── api-reference.ejs  ← /docs/api-reference
+└── assets/
+    ├── style.css          ← /assets/style.css (served normally)
+    └── script.js          ← /assets/script.js (served normally)
+```
+
+#### hideExtension with i18n middleware
+
+Combine `hideExtension` with `useOriginalUrl: false` for multilingual sites with clean URLs:
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+const ejs = require('ejs');
+
+const app = new Koa();
+
+// i18n middleware: /it/about → ctx.url = /about, ctx.state.lang = 'it'
+app.use(async (ctx, next) => {
+  const langMatch = ctx.path.match(/^\/(it|en|fr)\//);
+  if (langMatch) {
+    ctx.state.lang = langMatch[1];
+    ctx.url = ctx.path.replace(/^\/(it|en|fr)/, '') + ctx.search;
+  } else {
+    ctx.state.lang = 'en';  // Default language
+  }
+  await next();
+});
+
+app.use(koaClassicServer(__dirname + '/views', {
+  index: ['index.ejs'],
+  useOriginalUrl: false,     // Resolve files from rewritten URL
+  hideExtension: {
+    ext: '.ejs',
+    redirect: 301
+  },
+  template: {
+    ext: ['ejs'],
+    render: async (ctx, next, filePath) => {
+      ctx.body = await ejs.renderFile(filePath, { lang: ctx.state.lang });
+      ctx.type = 'text/html';
+    }
+  }
+}));
+
+app.listen(3000);
+```
+
+**Result:**
+
+| Request | Rewritten URL | File resolved | Redirect target |
+|---------|---------------|---------------|-----------------|
+| `/it/about` | `/about` | `views/about.ejs` | — |
+| `/en/blog/first-post` | `/blog/first-post` | `views/blog/first-post.ejs` | — |
+| `/it/about.ejs` | `/about.ejs` | — | 301 → `/it/about` (preserves `/it/` prefix) |
+
+> **Note**: Redirects always use `ctx.originalUrl` to preserve the language prefix, regardless of the `useOriginalUrl` setting.
+
+#### Temporary redirect (302)
+
+Use `redirect: 302` instead of 301 when the URL mapping may change (staging, A/B testing, or during migration):
+
+```javascript
+hideExtension: {
+  ext: '.ejs',
+  redirect: 302   // Temporary redirect — browsers won't cache it
+}
+```
+
+> **When to use 302**: A 301 (permanent) tells browsers and search engines to cache the redirect. Use 302 (temporary) during development, staging, or when you're not yet sure the clean URL structure is final.
+
+### 9. With HTTP Caching
 
 Enable aggressive caching for static files:
 
@@ -286,7 +412,7 @@ The default value for `browserCacheEnabled` is `false` to facilitate development
 
 **See details:** [HTTP Caching Optimization →](./docs/OPTIMIZATION_HTTP_CACHING.md)
 
-### 8. Multiple Index Files with Priority
+### 10. Multiple Index Files with Priority
 
 Search for multiple index files with custom order:
 
@@ -303,7 +429,7 @@ app.use(koaClassicServer(__dirname + '/public', {
 
 **See details:** [Index Option Priority →](./docs/INDEX_OPTION_PRIORITY.md)
 
-### 9. Complete Production Example
+### 11. Complete Production Example
 
 Real-world configuration for production:
 
@@ -326,9 +452,15 @@ app.use(koaClassicServer(path.join(__dirname, 'public'), {
   browserCacheMaxAge: 86400,  // 24 hours
 }));
 
-// Serve dynamic templates
+// Serve dynamic templates with clean URLs
 app.use(koaClassicServer(path.join(__dirname, 'views'), {
   showDirContents: false,
+  index: ['index.ejs'],
+  useOriginalUrl: false,  // Use ctx.url (for i18n or routing middleware)
+  hideExtension: {
+    ext: '.ejs',           // /about → serves about.ejs
+    redirect: 301          // /about.ejs → 301 redirect to /about
+  },
   template: {
     ext: ['ejs'],
     render: async (ctx, next, filePath) => {

package/docs/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to koa-classic-server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.1] - 2026-03-01
+
+### 📝 Documentation
+
+- Added dedicated usage example for `useOriginalUrl` (Section 7) with realistic i18n middleware scenario (/it/, /en/, /fr/)
+- Added "Advanced hideExtension Scenarios" section (Section 8):
+  - Recommended file/directory structure (ASCII tree)
+  - Combined `hideExtension` + i18n middleware example with `useOriginalUrl: false`
+  - Temporary redirect (302) variant with guidance on 301 vs 302 usage
+- Added `hideExtension` and `useOriginalUrl` to the Complete Production Example (Section 11)
+
+### 📦 Package Changes
+- **Version**: `2.5.0` → `2.5.1`
+- **Semver**: Patch version bump (documentation only, no code changes)
+
+---
+
 ## [2.5.0] - 2026-02-28
 
 ### ✨ New Feature

package/docs/DOCUMENTATION.md

@@ -90,13 +90,17 @@ Il middleware segue questo flusso per ogni richiesta HTTP:
 ### Dipendenze
 
 #### Production
-- **koa** (^2.13.4): Framework web minimale per Node.js
-- **mime-types**: Riconoscimento automatico MIME types (dependency implicita)
+- **mime-types** (^2.1.35): Riconoscimento automatico MIME types
+
+#### Peer Dependencies
+- **koa** (^2.0.0 || >=3.1.2): Framework web minimale per Node.js
 
 #### Development
-- **jest** (^29.7.0): Framework di testing
-- **supertest** (^7.0.0): Testing richieste HTTP
-- **inquirer** (^12.4.1): CLI interattiva per testing manuale
+- **jest** (^30.2.0): Framework di testing
+- **supertest** (^7.2.2): Testing richieste HTTP
+- **inquirer** (^13.3.0): CLI interattiva per testing manuale
+- **autocannon** (^8.0.0): HTTP benchmarking
+- **ejs** (^3.1.10): Template engine per i test
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "High-performance Koa middleware for serving static files with Apache-like directory listing, HTTP caching, template engine support, and comprehensive security fixes",
   "main": "index.cjs",
   "exports": {
@@ -37,13 +37,13 @@
     "mime-types": "^2.1.35"
   },
   "peerDependencies": {
-    "koa": "^2.0.0 || ^3.0.0"
+    "koa": "^2.0.0 || >=3.1.2"
   },
   "devDependencies": {
-    "autocannon": "^7.15.0",
+    "autocannon": "^8.0.0",
     "ejs": "^3.1.10",
-    "inquirer": "^12.4.1",
-    "jest": "^29.7.0",
-    "supertest": "^7.0.0"
+    "inquirer": "^13.3.0",
+    "jest": "^30.2.0",
+    "supertest": "^7.2.2"
   }
 }