Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mount
✓ import mount from 'koa-mount'
✗ 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
✓ import * as mount from 'koa-mount'
✗ import { 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.
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
Debug
Known issues
gotchaWhen 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.fixBe 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`.
affects: >=1.0.0
gotchaTo 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.fixStart your application with `DEBUG=koa-mount node your-app.js` (Unix-like) or `set DEBUG=koa-mount && node your-app.js` (Windows Command Prompt).
affects: >=1.0.0
gotchaThe `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.fixReview 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.
affects: >=4.2.0
gotchaOlder 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.fixEnsure 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.
affects: <7.6.0 (Node.js)
Errors
Common errors & fixes
Not Found (when accessing root path after mounting only sub-paths)
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.
fixExplicitly 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)
`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.
fixUse a default import: `import mount from 'koa-mount';`.
SyntaxError: await is only valid in async function (or similar async/await errors)
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.
fixUpgrade 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.
Audit
Dependencies
koarequiredkoa-mount is a middleware for Koa applications and requires a Koa instance to function. It is a peer dependency.