koa-classic-server 2.1.2 → 2.1.3

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,98 @@
+# This workflow will run tests using node and then publish a package to npm when a release is published
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+# Prevent multiple concurrent publish workflows
+concurrency:
+  group: npm-publish-${{ github.ref }}
+  cancel-in-progress: false
+
+# Set permissions for the workflow
+permissions:
+  contents: read
+  id-token: write  # Required for npm provenance
+
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build package
+        run: npm run build --if-present
+
+      - name: Cache build artifacts
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            node_modules
+            dist
+            build
+          key: build-${{ github.sha }}
+
+  publish-npm:
+    name: Publish to npm Registry
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+          cache: 'npm'
+
+      - name: Restore build artifacts
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            node_modules
+            dist
+            build
+          key: build-${{ github.sha }}
+
+      - name: Verify package version matches release tag
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          RELEASE_TAG=${GITHUB_REF#refs/tags/}
+          # Remove 'v' prefix if present in tag
+          RELEASE_VERSION=${RELEASE_TAG#v}
+
+          echo "Package version: $PACKAGE_VERSION"
+          echo "Release version: $RELEASE_VERSION"
+
+          if [ "$PACKAGE_VERSION" != "$RELEASE_VERSION" ]; then
+            echo "Error: Package version ($PACKAGE_VERSION) does not match release tag ($RELEASE_VERSION)"
+            exit 1
+          fi
+
+      - name: Publish to npm with provenance
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -8,9 +8,15 @@
 
 ---
 
-## 🎉 Version 2.1.2 - Production Release
+## 🎉 Version 2.1.3 - Configuration Update
 
-Version 2.1.2 is a **major production release** featuring performance optimizations, enhanced directory listing, and critical bug fixes.
+Version 2.1.3 updates the default caching behavior for better development experience while maintaining production-ready performance.
+
+### What's New in 2.1.3
+
+✅ **Development-Friendly Defaults** - `enableCaching` now defaults to `false` for easier development
+✅ **Production Guidance** - Clear documentation on enabling caching for production environments
+✅ **Enhanced Documentation** - Comprehensive notes on caching configuration and recommendations
 
 ### What's New in 2.1.2
 
@@ -228,10 +234,14 @@ app.use(koaClassicServer(__dirname + '/public', {
 }));
 ```
 
-**Benefits:**
+**⚠️ Important: Production Recommendation**
+
+The default value for `enableCaching` is `false` to facilitate development (where you want changes to be immediately visible). **For production environments, it is strongly recommended to set `enableCaching: 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 →](./docs/OPTIMIZATION_HTTP_CACHING.md)
 
@@ -357,7 +367,8 @@ Creates a Koa middleware for serving static files.
   },
 
   // HTTP caching configuration
-  enableCaching: true,      // Enable ETag & Last-Modified (default: true)
+  // NOTE: Default is false for development. Set to true in production for better performance!
+  enableCaching: false,     // Enable ETag & Last-Modified (default: false)
   cacheMaxAge: 3600,        // Cache-Control max-age in seconds (default: 3600 = 1 hour)
 }
 ```
@@ -373,7 +384,7 @@ Creates a Koa middleware for serving static files.
 | `urlsReserved` | Array | `[]` | Reserved directory paths (first-level only) |
 | `template.render` | Function | `undefined` | Template rendering function |
 | `template.ext` | Array | `[]` | Extensions for template rendering |
-| `enableCaching` | Boolean | `true` | Enable HTTP caching headers |
+| `enableCaching` | Boolean | `false` | Enable HTTP caching headers (recommended: `true` in production) |
 | `cacheMaxAge` | Number | `3600` | Cache duration in seconds |
 
 ---

package/docs/CHANGELOG.md

@@ -5,6 +5,84 @@ 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.1.3] - 2025-11-25
+
+### 🔧 Configuration Changes
+
+#### Changed Default Caching Behavior
+- **Change**: `enableCaching` default value changed from `true` to `false`
+- **Rationale**: Better development experience - changes are immediately visible without cache invalidation
+- **Production Impact**: **Users should explicitly set `enableCaching: true` in production environments**
+- **Benefits in Production**:
+  - 80-95% bandwidth reduction
+  - Faster page loads with 304 Not Modified responses
+  - Reduced server load
+- **Code**: `index.cjs:107`
+
+### 📝 Documentation Improvements
+
+#### Enhanced Caching Documentation
+- Added comprehensive production recommendations in README.md
+- Added inline code comments explaining the default behavior
+- Clear guidance on when to enable caching (development vs production)
+- **Files**: `README.md`, `index.cjs`
+
+### ⚠️ Migration Notice
+
+**IMPORTANT**: If you are upgrading from 2.1.2 or earlier and rely on HTTP caching:
+
+```javascript
+// You must now explicitly enable caching in production
+app.use(koaClassicServer(__dirname + '/public', {
+  enableCaching: true  // ← Add this for production environments
+}));
+```
+
+**Development**: No changes needed - the new default (`false`) is better for development.
+
+**Production**: Explicitly set `enableCaching: true` to maintain previous behavior and performance benefits.
+
+### 📦 Package Changes
+
+- **Version**: `2.1.2` → `2.1.3`
+
+---
+
+## [2.1.2] - 2025-11-24
+
+### 🎨 Features
+
+#### Sortable Directory Columns
+- Apache2-like directory listing with clickable column headers
+- Sort by Name, Type, or Size (ascending/descending)
+- Fixed navigation bug after sorting
+
+#### File Size Display
+- Human-readable file sizes (B, KB, MB, GB, TB)
+- Proper formatting and precision
+
+#### HTTP Caching
+- ETag and Last-Modified headers
+- 304 Not Modified responses
+- 80-95% bandwidth reduction
+
+### 🧪 Testing
+- 153 tests passing
+- Comprehensive test coverage
+
+---
+
+## [2.1.1] - 2025-11-23
+
+### 🚀 Production Release
+
+- Async/await implementation
+- Non-blocking I/O
+- Performance optimizations
+- Flow documentation
+
+---
+
 ## [1.2.0] - 2025-11-17
 
 ### 🎉 SECURITY & BUG FIX RELEASE

package/index.cjs

@@ -45,7 +45,10 @@ module.exports = function koaClassicServer(
             ext: [], // File extensions to process with template.render
         },
         cacheMaxAge: 3600, // Cache-Control max-age in seconds (default: 1 hour)
-        enableCaching: true, // Enable HTTP caching headers (ETag, Last-Modified)
+        enableCaching: false, // Enable HTTP caching headers (ETag, Last-Modified)
+                              // NOTE: Default is false for development.
+                              // In production, it's recommended to set enableCaching: true
+                              // to reduce bandwidth usage and improve performance.
     }
     */
 ) {
@@ -97,8 +100,11 @@ module.exports = function koaClassicServer(
     options.template.ext = Array.isArray(options.template.ext) ? options.template.ext : [];
 
     // OPTIMIZATION: HTTP Caching options
+    // NOTE: Default enableCaching is false for development environments.
+    // For production deployments, it's strongly recommended to enable caching
+    // by setting enableCaching: true to benefit from reduced bandwidth and improved performance.
     options.cacheMaxAge = typeof options.cacheMaxAge === 'number' && options.cacheMaxAge >= 0 ? options.cacheMaxAge : 3600;
-    options.enableCaching = typeof options.enableCaching === 'boolean' ? options.enableCaching : true;
+    options.enableCaching = typeof options.enableCaching === 'boolean' ? options.enableCaching : false;
 
     return async (ctx, next) => {
         // Check if method is allowed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "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": {
@@ -29,6 +29,10 @@
   ],
   "author": "Italo Paesano",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/italopaesano/koa-classic-server"
+  },
   "dependencies": {
     "mime-types": "^2.1.35"
   },