{"id":17799,"library":"middle-router","title":"Universal Middleware Router","description":"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.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/thetalecrafter/middle-router","tags":["javascript","router","url","middleware","universal","isomorphic"],"install":[{"cmd":"npm install middle-router","lang":"bash","label":"npm"},{"cmd":"yarn add middle-router","lang":"bash","label":"yarn"},{"cmd":"pnpm add middle-router","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `Router` constructor/factory function is exported as the default export. Destructuring it from the package will result in `undefined`.","wrong":"import { Router } from 'middle-router'","symbol":"Router Constructor (ESM)","correct":"import Router from 'middle-router'"},{"note":"In CommonJS environments, the `Router` constructor is the direct `module.exports`. Attempting to destructure it as a named export will not work as expected.","wrong":"const { Router } = require('middle-router')","symbol":"Router Constructor (CommonJS)","correct":"const Router = require('middle-router')"},{"note":"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.","wrong":"import Router from 'middle-router'; const myRouter = new Router();","symbol":"Router Instance Creation","correct":"import Router from 'middle-router'; const myRouter = Router();"}],"quickstart":{"code":"import Router from 'middle-router';\n\nconst appRouter = Router()\n  .use(async ({ context, next }) => {\n    const start = Date.now();\n    console.log(`[Middleware 1] Entering: ${context.url}`);\n    await next(); // Pass control to the next middleware\n    const duration = Date.now() - start;\n    context.totalTime = duration;\n    console.log(`[Middleware 1] Exiting: ${context.url} (took ${duration}ms)`);\n  })\n  .use('/users/:id', async ({ params, resolve, context }) => {\n    console.log(`[Middleware 2] Matched /users/${params.id}`);\n    // Simulate async data fetching\n    await new Promise(res => setTimeout(res, 50));\n    const userData = { id: params.id, name: `User ${params.id}`, fetchedAt: Date.now() };\n    resolve(`<h1>User Profile</h1><p>ID: ${userData.id}</p><p>Name: ${userData.name}</p><p>Fetched at: ${userData.fetchedAt}</p>`);\n    console.log(`[Middleware 2] Resolved for /users/${params.id}`);\n  })\n  .use(async ({ resolve, context }) => {\n    console.log(`[Middleware 3] Default catch-all for: ${context.url}`);\n    resolve(`<h1>Welcome</h1><p>No specific route matched for ${context.url}.</p>`);\n  });\n\nasync function runExample() {\n  console.log('--- Routing /users/123 ---');\n  const userView = await appRouter.route('/users/123', { initialData: '...' });\n  console.log('Resolved View:', userView);\n  console.log('\\n--- Routing /about ---');\n  const aboutView = await appRouter.route('/about');\n  console.log('Resolved View:', aboutView);\n  console.log('\\n--- Routing / ---');\n  const homeView = await appRouter.route('/');\n  console.log('Resolved View:', homeView);\n}\n\nrunExample();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Misunderstanding 'await exiting' lifecycle","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Potential changes to middleware signature between major versions","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Client-side routing requires explicit initialization and event handling","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import Router from 'middle-router'` to correctly access the default exported constructor.","cause":"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`.","error":"TypeError: Router is not a function"},{"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.","cause":"An asynchronous middleware function completed execution without explicitly calling `resolve()` to yield a result, calling `next()` to pass control, or throwing an error.","error":"Middleware did not call resolve() or throw an error, leading to a hang or timeout."},{"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`.","cause":"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.","error":"Invariant Violation: You should not use <Router> outside a <BrowserRouter>"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}