Registry / http-networking / middle-router

middle-router

library2.2.0jsnpmunverified

middle-router is a universal routing library designed for both client-side and server-side JavaScript applications, allowing URL changes to be processed through a series of asynchronous middleware functions. As of version 2.2.0, it provides a consistent API for managing routing logic across different environments. It distinguishes itself by integrating Koa-style `await next()` patterns for middleware execution, enabling control to flow downstream and then back upstream. This allows for complex lifecycle management around route changes, such as measuring execution time, handling exit conditions, or even prompting before navigation. The library leverages `path-to-regexp` for flexible path matching, similar to Express 4.x, and utilizes `middle-run` for robust middleware orchestration. While the provided examples often showcase integration with frameworks like Express and React, `middle-router` itself is entirely framework-agnostic, offering core routing functionality without imposing external dependencies. It focuses on providing a flexible and powerful middleware-based approach to handling application state changes tied to URLs. Its release cadence is stable, with new features and bug fixes rolled out incrementally.

http-networking web-framework

npm install middle-router

github ↗package ↗

INSTALL

IMPORT

SIG · MIDDLE-ROUTER

middle-router

http-networkingjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Router Constructor (ESM)

✓ import Router from 'middle-router'

✗ import { Router } from 'middle-router'

The `Router` constructor/factory function is exported as the default export. Destructuring it from the package will result in `undefined`.

Router Constructor (CommonJS)

✓ const Router = require('middle-router')

✗ const { Router } = require('middle-router')

In CommonJS environments, the `Router` constructor is the direct `module.exports`. Attempting to destructure it as a named export will not work as expected.

Router Instance Creation

✓ import Router from 'middle-router'; const myRouter = Router();

✗ import Router from 'middle-router'; const myRouter = new Router();

The `Router` from `middle-router` is a factory function; it should be called directly (e.g., `Router()`) to create a router instance, not instantiated with the `new` keyword.

This quickstart demonstrates how to create a `middle-router` instance, define asynchronous middleware functions for different paths, and use `router.route()` to process URLs, simulating both specific and default route handling in a Node.js environment.

import Router from 'middle-router'; const appRouter = Router() .use(async ({ context, next }) => { const start = Date.now(); console.log(`[Middleware 1] Entering: ${context.url}`); await next(); // Pass control to the next middleware const duration = Date.now() - start; context.totalTime = duration; console.log(`[Middleware 1] Exiting: ${context.url} (took ${duration}ms)`); }) .use('/users/:id', async ({ params, resolve, context }) => { console.log(`[Middleware 2] Matched /users/${params.id}`); // Simulate async data fetching await new Promise(res => setTimeout(res, 50)); const userData = { id: params.id, name: `User ${params.id}`, fetchedAt: Date.now() }; resolve(`<h1>User Profile</h1><p>ID: ${userData.id}</p><p>Name: ${userData.name}</p><p>Fetched at: ${userData.fetchedAt}</p>`); console.log(`[Middleware 2] Resolved for /users/${params.id}`); }) .use(async ({ resolve, context }) => { console.log(`[Middleware 3] Default catch-all for: ${context.url}`); resolve(`<h1>Welcome</h1><p>No specific route matched for ${context.url}.</p>`); }); async function runExample() { console.log('--- Routing /users/123 ---'); const userView = await appRouter.route('/users/123', { initialData: '...' }); console.log('Resolved View:', userView); console.log('\n--- Routing /about ---'); const aboutView = await appRouter.route('/about'); console.log('Resolved View:', aboutView); console.log('\n--- Routing / ---'); const homeView = await appRouter.route('/'); console.log('Resolved View:', homeView); } runExample();

Debug

Known issues

gotchaMisunderstanding 'await exiting' lifecycle

fix

Ensure `await exiting` is placed *after* `resolve()` in your middleware. Placing it before `resolve()` will prevent the route from resolving until the next URL change occurs, leading to unexpected behavior and potential hangs.

affects: >=1.0.0

breakingPotential changes to middleware signature between major versions

fix

When upgrading major versions, always review the official API documentation for your specific major version. The expected arguments for middleware functions (`{ context, next, params, resolve, etc. }`) may have undergone significant changes or reordering.

affects: >=2.0.0

gotchaClient-side routing requires explicit initialization and event handling

fix

For browser-based client-side routing, ensure you explicitly call `router.on('route', handler)` to process the resolved view data and `router.start()` to initiate routing and listen for browser history (e.g., `popstate`) and hash changes.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Router is not a function

Attempting to import `Router` as a named export (e.g., `import { Router } from 'middle-router'`) when it is the default export, resulting in `Router` being `undefined`.

fix

Change your import statement to `import Router from 'middle-router'` to correctly access the default exported constructor.

Middleware did not call resolve() or throw an error, leading to a hang or timeout.

An asynchronous middleware function completed execution without explicitly calling `resolve()` to yield a result, calling `next()` to pass control, or throwing an error.

fix

Ensure all execution paths within your middleware functions either call `resolve(viewData)`, call `await next()` (if passing control to subsequent middleware), or explicitly throw an error to prevent the routing process from hanging indefinitely.

Invariant Violation: You should not use <Router> outside a <BrowserRouter>

This error message is specific to React Router and indicates a common misunderstanding: `middle-router` is a standalone, framework-agnostic routing library, not a wrapper or replacement for React Router components. The error occurs when a React Router component is used without its necessary context provider.

fix

Remember that `middle-router` provides core routing logic. If integrating with React, it supplies the 'view' (e.g., a React element) that you then render with `ReactDOM`, but it does not replace or depend on `react-router-dom`.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/thetalecrafter/middle-router ↗

packagehttps://www.npmjs.com/package/middle-router ↗