Koa Mount Middleware

4.2.0 · active · verified Wed Apr 22

koa-mount is a lightweight middleware package for the Koa web framework, designed to facilitate the mounting of other Koa applications or individual Koa middleware functions at specific URL paths. When a request matches a mounted path, koa-mount temporarily strips that path segment from the URL before passing the request downstream, allowing the mounted component to operate as if it were at the root of the application. This mechanism promotes modular application development by encapsulating sub-applications or middleware logic independently of their deployment path. The package is currently stable at version 4.2.0, with releases focusing on enhancements and bug fixes, indicating a mature and actively maintained status within the Koa ecosystem. It differentiates itself by providing a clear and efficient way to compose complex Koa applications from smaller, isolated parts.

Common errors

```
Not Found (when accessing root path after mounting only sub-paths)
```
cause By default, `koa-mount` only handles requests matching the specified path. If no middleware or application is mounted at the root path ('/'), Koa's default 404 handler will be invoked for root requests.

fix Explicitly mount a handler or another Koa application at the root path ('/') if you want it to respond to root requests, e.g., `app.use(mount('/', rootApp));` or `app.use(async ctx => { ctx.body = 'Welcome!'; });`
```
TypeError: mount is not a function (when using ES module named import)
```
cause `koa-mount` exports its primary function as a default export. Attempting to import it using named import syntax (`{ mount }`) will cause this error because no named export 'mount' exists.

fix Use a default import: `import mount from 'koa-mount';`.
```
SyntaxError: await is only valid in async function (or similar async/await errors)
```
cause This typically indicates that the Node.js version running the application does not support `async`/`await` syntax, or the code is being run in a context where `async`/`await` is not permitted without explicit declaration (e.g., top-level await in an older Node.js version or non-ESM script). `koa-mount` itself is async/await compatible, but the environment must support it.

fix Upgrade Node.js to a version that fully supports `async`/`await` (>= 7.6.0, but ideally an active LTS version). Ensure your project is configured for ESM if using top-level `await` or if you're mixing module types.

Warnings

gotcha When using `koa-mount`, the `ctx.path` property inside the mounted application or middleware is relative to the mount point, not the original request URL. Developers must account for this path stripping when constructing URLs or processing routes within the mounted context.
Fix: Be aware that `ctx.path` will be transformed. If you need the full original path, access `ctx.originalUrl` or `ctx.request.url` before the `mount` middleware. You can also reconstruct the full path using `ctx.mountPath + ctx.path`.
gotcha To enable detailed debug logging for `koa-mount`, you must set the `DEBUG` environment variable to `koa-mount` before starting your Node.js application. Without this, no specific `koa-mount` debug output will be visible.
Fix: Start your application with `DEBUG=koa-mount node your-app.js` (Unix-like) or `set DEBUG=koa-mount && node your-app.js` (Windows Command Prompt).
gotcha The `v4.2.0` release introduced automatic composition of middleware when passed an array or multiple arguments. While a feature, this could subtly change behavior if users previously relied on specific manual composition logic, or had nested arrays that now behave differently.
Fix: Review your middleware composition logic, especially if passing arrays of middleware or multiple middleware arguments to `mount()`, to ensure the automatic composition aligns with expected behavior. Test thoroughly after upgrading to v4.2.0.
gotcha Older Node.js versions (e.g., prior to 7.6.0) are not supported. Using `koa-mount` with `async/await` syntax on an unsupported Node.js version will lead to syntax errors or runtime failures.
Fix: Ensure your Node.js environment is at least version 7.6.0. It is generally recommended to use an active LTS Node.js version for production applications.

Install

npm install koa-mount npm
yarn add koa-mount yarn
pnpm add koa-mount pnpm

Imports

mount
wrong:
```
import { mount } from 'koa-mount'
```
correct:
```
import mount from 'koa-mount'
```
koa-mount is exported as a default function. Using named import syntax (curly braces) will result in an error or undefined.
mount
```
const mount = require('koa-mount')
```
This is the standard CommonJS import pattern, shown in the official examples.
* as mount
wrong:
```
import { mount } from 'koa-mount'
```
correct:
```
import * as mount from 'koa-mount'
```
While less common for a single default export, this pattern will correctly import the module as an object with a default property referencing the mount function. Still, `import mount from 'koa-mount'` is preferred.

Quickstart

This example demonstrates how to mount two separate Koa applications, 'a' and 'b', at distinct paths '/hello' and '/world' respectively, within a main Koa application. It illustrates `koa-mount`'s primary use case for creating modular web services where sub-applications handle specific route prefixes. Requests to '/hello' trigger app 'a', and '/world' trigger app 'b', while requests to the root '/' result in a 404.

import Koa from 'koa';
import mount from 'koa-mount';

// A small Koa application named 'a'
const a = new Koa();
a.use(async function (ctx, next){
  await next();
  ctx.body = 'Hello';
});

// Another small Koa application named 'b'
const b = new Koa();
b.use(async function (ctx, next){
  await next();
  ctx.body = 'World';
});

// The main Koa application
const app = new Koa();

// Mount 'a' at '/hello' and 'b' at '/world'
app.use(mount('/hello', a));
app.use(mount('/world', b));

app.listen(3000, () => {
  console.log('Koa app listening on port 3000');
  console.log('Try visiting:');
  console.log('  GET http://localhost:3000/hello');
  console.log('  GET http://localhost:3000/world');
  console.log('  GET http://localhost:3000/');
});

// To run this example:
// 1. Save as `app.mjs` (for ESM support)
// 2. npm install koa koa-mount
// 3. node app.mjs

view raw JSON →