or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-koa-mount

Mounting middleware for Koa.js applications that enables mounting apps and middleware at specific path prefixes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/koa-mount@4.2.x

To install, run

npx @tessl/cli install tessl/npm-koa-mount@4.2.0

index.mddocs/

Koa Mount

Koa Mount provides mounting middleware for Koa.js applications that enables mounting entire Koa applications or individual middleware functions at specific path prefixes. It strips the mount path from the URL temporarily until the stack unwinds, allowing mounted apps and middleware to function correctly regardless of which path segments they operate on.

Package Information

  • Package Name: koa-mount
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install koa-mount

Core Imports

const mount = require('koa-mount');

ES modules (if using a bundler that supports CommonJS imports):

import mount from 'koa-mount';

Basic Usage

const mount = require('koa-mount');
const Koa = require('koa');

// Create sub-applications
const blogApp = new Koa();
blogApp.use(async (ctx) => {
  ctx.body = 'Blog content';
});

const apiApp = new Koa();
apiApp.use(async (ctx) => {
  ctx.body = { message: 'API response' };
});

// Mount applications at different paths
const app = new Koa();
app.use(mount('/blog', blogApp));
app.use(mount('/api', apiApp));

app.listen(3000);

Capabilities

Mount Function

The primary export that mounts Koa applications or middleware at specified path prefixes.

/**
 * Mount app with prefix, app may be a Koa application or middleware function
 * @param {String|Application|Function} prefix - Path prefix or app/middleware when path is omitted
 * @param {Application|Function} [app] - Koa application, middleware function, or array of middleware
 * @returns {Function} Koa middleware function
 */
function mount(prefix, app);

Usage Patterns:

  1. Mount at root path (defaults to "/"):
app.use(mount(koaApp));
  1. Mount application at specific path:
app.use(mount('/blog', blogApp));
  1. Mount middleware function:
app.use(mount('/api', async (ctx, next) => {
  ctx.body = 'API endpoint';
  await next();
}));
  1. Mount array of middleware:
app.use(mount('/admin', [
  authMiddleware,
  adminMiddleware
]));
  1. Cascading mounts (nested mounting):
const app = new Koa();
const blogApp = new Koa();
const adminApp = new Koa();

// Mount admin at /blog/admin
blogApp.use(mount('/admin', adminApp));
app.use(mount('/blog', blogApp));

// Request to /blog/admin/users will cascade through both mounts

Path Matching Behavior

The mount function implements precise path matching rules:

  • Exact prefix matching: /prefix matches /prefix, /prefix/, /prefix/anything
  • Trailing slash sensitivity: /prefix/ only matches paths with trailing slash after prefix
  • Word boundary protection: /prefix does not match /prefixother
  • Path transformation: Mount prefix is stripped from ctx.path during middleware execution

Context Modifications

When mounting at non-root paths, the mount middleware modifies the Koa context:

interface KoaContext {
  /** Original request path, temporarily modified during mounted middleware execution */
  path: string;
  /** Set to the mount prefix path during execution (only when not mounting at "/") */
  mountPath?: string;
}

Example of path transformation:

// Request to "/blog/posts/123" with mount prefix "/blog"
// Inside mounted middleware: ctx.path becomes "/posts/123"
// ctx.mountPath is set to "/blog"
// After middleware completes: ctx.path restored to "/blog/posts/123"

Error Handling

The mount function includes validation and proper error handling:

  • Path validation: Mount path must start with "/" (throws assertion error if not)
  • Error propagation: Errors in mounted middleware properly bubble up to parent application
  • Path restoration: Context path is restored even when errors occur in mounted middleware

Debugging Support

Built-in debugging capabilities using the debug module:

DEBUG=koa-mount node app.js

Debug output includes:

  • Mount point registration
  • Path matching and transformation events
  • Enter/leave events during middleware execution

Example debug output:

koa-mount mount /blog blogApp +0ms
koa-mount enter /blog/posts -> /posts +1ms
koa-mount leave /blog/posts -> /posts +5ms

Types

Supported Application Types

interface KoaApplication {
  /** Array of middleware functions (used for mounting full applications) */
  middleware: Function[];
  /** Optional name for debugging purposes */
  name?: string;
}

Middleware Function Type

/**
 * Standard Koa middleware function signature
 * @param {Object} ctx - Koa context object
 * @param {Function} next - Next middleware function
 */
type MiddlewareFunction = (ctx: Object, next: Function) => Promise<void>;

Dependencies

The mount function relies on these external dependencies:

  • debug: Debug logging with namespace 'koa-mount'
  • koa-compose: Composes middleware arrays into single middleware function
  • assert: Node.js assertion module for path validation