{"id":17110,"library":"koa-mount","title":"Koa Mount Middleware","description":"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.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/mount","tags":["javascript","koa","middleware","mount","mounting"],"install":[{"cmd":"npm install koa-mount","lang":"bash","label":"npm"},{"cmd":"yarn add koa-mount","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-mount","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"koa-mount is a middleware for Koa applications and requires a Koa instance to function. It is a peer dependency.","package":"koa","optional":false}],"imports":[{"note":"koa-mount is exported as a default function. Using named import syntax (curly braces) will result in an error or undefined.","wrong":"import { mount } from 'koa-mount'","symbol":"mount","correct":"import mount from 'koa-mount'"},{"note":"This is the standard CommonJS import pattern, shown in the official examples.","symbol":"mount","correct":"const mount = require('koa-mount')"},{"note":"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.","wrong":"import { mount } from 'koa-mount'","symbol":"* as mount","correct":"import * as mount from 'koa-mount'"}],"quickstart":{"code":"import Koa from 'koa';\nimport mount from 'koa-mount';\n\n// A small Koa application named 'a'\nconst a = new Koa();\na.use(async function (ctx, next){\n  await next();\n  ctx.body = 'Hello';\n});\n\n// Another small Koa application named 'b'\nconst b = new Koa();\nb.use(async function (ctx, next){\n  await next();\n  ctx.body = 'World';\n});\n\n// The main Koa application\nconst app = new Koa();\n\n// Mount 'a' at '/hello' and 'b' at '/world'\napp.use(mount('/hello', a));\napp.use(mount('/world', b));\n\napp.listen(3000, () => {\n  console.log('Koa app listening on port 3000');\n  console.log('Try visiting:');\n  console.log('  GET http://localhost:3000/hello');\n  console.log('  GET http://localhost:3000/world');\n  console.log('  GET http://localhost:3000/');\n});\n\n// To run this example:\n// 1. Save as `app.mjs` (for ESM support)\n// 2. npm install koa koa-mount\n// 3. node app.mjs","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<7.6.0 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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!'; });`","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.","error":"Not Found (when accessing root path after mounting only sub-paths)"},{"fix":"Use a default import: `import mount from 'koa-mount';`.","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.","error":"TypeError: mount is not a function (when using ES module named import)"},{"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.","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.","error":"SyntaxError: await is only valid in async function (or similar async/await errors)"}],"ecosystem":"npm","meta_description":null}