Serving Static Assets: express vs koa-static vs serve-static

When you need to deliver HTML, JavaScript, CSS, images, or other static files from a Node.js backend, your choice of tool depends heavily on your application’s architecture. The packages express, koa-static, and serve-static are often mentioned together, but they solve different problems at different layers. Let’s clarify what each does — and when to use which.

🧱 Core Roles: Framework vs Middleware

express is a full web application framework. It handles routing, middleware, request parsing, and response formatting. While it can serve static files, it delegates that job to middleware like serve-static.

// express alone cannot serve static files efficiently
// You must use serve-static as middleware
import express from 'express';
const app = express();

// This won't work without serve-static
// app.use(express.static('public')); // actually uses serve-static under the hood

💡 Note: express.static is just an alias for serve-static. When you call express.static(), you’re using the serve-static package.

serve-static is a standalone middleware designed specifically to serve static files. It works with Express, Connect, or any framework that follows the (req, res, next) middleware signature.

// Using serve-static directly (though usually via express.static)
import serveStatic from 'serve-static';
import finalhandler from 'finalhandler';
import http from 'http';
import fs from 'fs';

const serve = serveStatic('public', { index: ['index.html'] });

const server = http.createServer((req, res) => {
  serve(req, res, finalhandler(req, res));
});

koa-static is the Koa-specific equivalent of serve-static. It only works in Koa applications and leverages Koa’s context (ctx) object and async middleware model.

// koa-static in a Koa app
import Koa from 'koa';
import serve from 'koa-static';

const app = new Koa();
app.use(serve('public'));

⚙️ How Static Serving Actually Works

None of these packages are “static servers” by themselves — except when composed properly. Here’s how each is typically used:

With Express (using serve-static under the hood)

import express from 'express';
const app = express();

// This is the standard way
app.use(express.static('public', {
  maxAge: '1d',
  etag: true,
  fallthrough: false
}));

app.listen(3000);

Under the hood, express.static = require('serve-static'). So you’re really using serve-static.

With Koa (using koa-static)

import Koa from 'koa';
import serve from 'koa-static';

const app = new Koa();
app.use(serve('public', {
  maxage: 86400000, // 1 day in ms
  hidden: false,
  index: 'index.html'
}));

app.listen(3000);

Standalone with serve-static (no framework)

import http from 'http';
import serveStatic from 'serve-static';
import finalhandler from 'finalhandler';
import path from 'path';

const serve = serveStatic(path.join(process.cwd(), 'public'), {
  index: ['index.html']
});

http.createServer((req, res) => {
  serve(req, res, finalhandler(req, res));
}).listen(3000);

🔒 Important: serve-static requires a final handler (like finalhandler) to manage 404s and errors in standalone mode.

🛠️ Feature Comparison: Caching, Security, and Control

All three approaches support common static-serving needs, but through different APIs.

Setting Cache Headers

Express / serve-static:

app.use(express.static('public', {
  maxAge: '7d',
  etag: true
}));

Koa / koa-static:

app.use(serve('public', {
  maxage: 7 * 24 * 60 * 60 * 1000, // 7 days in ms
  immutable: true
}));

Note the spelling difference: maxAge (serve-static) vs maxage (koa-static).

Handling Hidden Files

serve-static hides dotfiles by default (dotfiles: 'ignore'). You can allow them:

express.static('public', { dotfiles: 'allow' })

koa-static also hides them by default (hidden: false). Enable with:

serve('public', { hidden: true })

Custom Index Files

Both let you define fallback index files:

// serve-static
express.static('public', { index: ['default.html', 'index.html'] })

// koa-static
serve('public', { index: 'default.html' }) // only accepts string, not array

⚠️ Limitation: koa-static only supports a single index filename, while serve-static accepts an array for fallbacks.

🔄 Framework Compatibility: Don’t Mix Ecosystems

• serve-static works with Express, Connect, or any (req, res, next) middleware system. It does not work with Koa.
• koa-static only works with Koa. It will throw errors if used in an Express app.
• express is a complete framework — you don’t “add” it to Koa or vice versa.

Trying to use koa-static in Express:

// ❌ This fails
import express from 'express';
import koaStatic from 'koa-static';

const app = express();
app.use(koaStatic('public')); // TypeError: ctx is not defined

Similarly, serve-static won’t work in Koa without adaptation:

// ❌ This also fails
import Koa from 'koa';
import serveStatic from 'serve-static';

const app = new Koa();
app.use(serveStatic('public')); // Doesn't match Koa's async middleware signature

🧪 When to Use What: Real Scenarios

Scenario 1: Building a Full REST API + Frontend Bundle

You have an Express backend serving JSON APIs and also need to deliver a React SPA.

• ✅ Use: express + express.static() (i.e., serve-static)
• Why? Tight integration, same codebase, easy routing precedence control.

app.use('/api/users', userRoutes);
app.use(express.static('build')); // serves index.html for SPA

Scenario 2: Lightweight Koa Microservice with Static Docs

You’re using Koa for its async simplicity and need to serve Swagger UI or docs.

• ✅ Use: koa-static
• Why? Native Koa middleware, no extra abstraction layer.

app.use(serve('docs'));

Scenario 3: Minimal Static File Server (No Routing Needed)

You just want to serve a folder over HTTP with caching and gzip.

• ✅ Use: serve-static directly with Node’s http module
• Why? Avoid framework overhead; serve-static is battle-tested for this exact use case.

🚫 Common Misconceptions

• Myth: “express serves static files natively.”

  • Truth: It relies entirely on serve-static via express.static.

• Myth: “koa-static is a drop-in replacement for serve-static.”

  • Truth: They belong to incompatible middleware systems.

• Myth: “I can use serve-static in Koa with a wrapper.”

  • Truth: Possible, but not recommended — use koa-static instead for cleaner code.

📊 Summary Table

💡 Final Guidance

• If you’re using Express, serve static files with express.static() — which is serve-static.
• If you’re using Koa, reach for koa-static.
• Never use express just to serve static files — that’s overkill. Use serve-static standalone or with a minimal server.
• Never mix middleware across ecosystems — it leads to runtime errors and maintenance headaches.

The right choice isn’t about which package is “better” — it’s about matching the tool to your application’s foundation. Get that right, and static asset delivery becomes a solved problem.