A lightweight JavaScript library that matches paths against registered routes. It includes support for dynamic and star segments and nested handlers.
JavaScript CSS Ruby
Pull request Compare This branch is 177 commits behind tildeio:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status


route-recognizer is a lightweight JavaScript library (under 2k!) that can be used as the recognizer for a more comprehensive router system (such as router.js).

In keeping with the Unix philosophy, it is a modular library that does one thing and does it well.


Create a new router:

var router = new Router();

Add a simple new route description:

router.add([{ path: "/posts", handler: handler }]);

The handler is an opaque object with no specific meaning to route-recognizer. A module using route-recognizer could use functions or other objects with domain-specific semantics for what to do with the handler.

A route description can have handlers at various points along the path:

  { path: "/admin", handler: admin },
  { path: "/posts", handler: posts }

Recognizing a route will return a list of the handlers and their associated parameters:

var result = router.recognize("/admin/posts");
result === [
  { handler: admin, params: {} },
  { handler: posts, params: {} }

Dynamic segments:

  { path: "/posts/:id", handler: posts },
  { path: "/comments", handler: comments }

result = router.recognize("/posts/1/comments");
result === [
  { handler: posts, params: { id: "1" } },
  { handler: comments, params: {} }

A dynamic segment matches any character but /.

Star segments:

router.add([{ path: "/pages/*path", handler: page }]);

result = router.recognize("/pages/hello/world");
result === [{ handler: page, params: { path: "hello/world" } }];


If multiple routes all match a path, route-recognizer will pick the one with the fewest dynamic segments:

router.add({ path: "/posts/edit", handler: editPost });
router.add({ path: "/posts/:id", handler: showPost });
router.add({ path: "/posts/new", handler: newPost });

var result1 = router.recognize("/posts/edit");
result1 === [{ handler: editPost, params: {} }];

var result2 = router.recognize("/posts/1");
result2 === [{ handler: showPost, params: { id: "1" } }];

var result3 = router.recognize("/posts/new");
result3 === [{ handler: newPost, params: {} }];

As you can see, this has the expected result. Explicit static paths match more closely than dynamic paths.