koa-mount

koa-mount lets you attach an entire Koa application, an array of middleware, or a single middleware function to a specific URL path prefix within a parent Koa app. While a request is inside the mounted stack, koa-mount temporarily strips the prefix from ctx.path so the mounted code sees paths exactly as if it were running standalone at the root — then restores the original path when control returns upstream, even across nested mounts.

This makes it possible to compose several independent Koa apps (a blog, an admin panel, a static file server) into one process without any of them needing to know where they’ll ultimately be served from. It’s a small, focused utility rather than a router: it does one thing — path-prefix isolation for composition — and has been a standard piece of the Koa ecosystem for over a decade.

What You Get

• A mount(prefix, app) function that accepts a Koa application instance, an array of middleware, or a single middleware function
• Automatic path-prefix stripping on entry and restoration on exit (including through nested mounts), implemented with a try/finally guard
• Support for mounting at the default / path when the prefix argument is omitted
• Correct handling of trailing-slash vs non-trailing-slash prefixes so /mount doesn’t accidentally match /mountlkjalskjdf
• NODE_DEBUG=koa-mount environment variable support for tracing enter/leave path transitions during debugging

Common Use Cases

• Composing multiple independently-developed Koa apps (e.g. a blog and an admin dashboard) into a single process under different path prefixes
• Serving static assets from a specific sub-path using koa-static mounted under a prefix like /examples or /assets
• Nesting mounted apps inside other mounted apps to build a tree of path-scoped functionality (/foo containing /foo/bar containing /foo/bar/baz)
• Wrapping a third-party or vendored Koa middleware so it can be dropped into a larger app at an arbitrary path without modification

Under The Hood

Architecture The entire package is a single ~100-line file (index.js) exporting one mount(prefix, app) function; there are no classes, registries, or internal state beyond closures. When app is an array or a full Koa application (detected via its .middleware property), koa-mount composes it into one function using koa-compose. The returned middleware saves the current ctx.path, computes the stripped path via a private match() helper, temporarily overwrites ctx.path for the duration of the downstream call, restores the original path around any call to upstream() so code later in the outer stack sees the real URL, and restores it again on exit inside a finally block so the path is always correctly unwound even if the downstream stack throws. Nesting mounts inside mounts composes cleanly because each layer only ever touches and restores its own segment of ctx.path.

Tech Stack A CommonJS Node package with a single runtime dependency, koa-compose, and a peer dependency on koa (>= 2). Development tooling is comprehensive for the package’s size: xo for linting (an opinionated ESLint config run as a pretest step), the built-in Node test runner plus supertest for HTTP-level assertions, c8 for coverage, husky for git hooks, and np for release publishing. There is no build/transpile step — the module is published as plain CommonJS and targets Node >= 22.

Code Quality Tests live under test/ and cover the core scenarios directly: default-path mounting, prefixed mounting, cascading through nested mounts, prefix restoration around next(), and serving static assets through a mount via a separate acceptance test. Error handling is minimal by design — a single assert.equal check guards against prefixes that don’t start with /, and the path-restoration logic itself relies on try/finally rather than explicit error branching. Naming is terse and consistent with Koa’s own conventions (ctx, prefix, downstream, upstream). No TypeScript types are bundled. CI runs the full test-and-lint suite on GitHub Actions across three Node versions (22, 24, 26) on every push, and Dependabot keeps the single dependency current.

What Makes It Unique There’s nothing novel here by design — koa-mount solves one narrow problem (prefix-transparent composition of Koa apps and middleware) the same way it has since Koa’s early days, and its value is in staying that small and stable rather than accumulating routing or dispatch features that would duplicate what dedicated routers already do.