Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Cortex is a wrapper for Backbone routes that makes them function like routes in Express, allowing you to define middleware functions for each route.


Include the Cortex source after Backbone and its dependencies have been loaded

<script type="text/javascript" src="<path>/cortex-x.x.x.min.js"></script>


	var cortex = new Cortex();

	// Event handler for when a middleware or route
	// handler throws an exception
	cortex.on('error', function(err, route){

	// Event for post-route handling.
	// This will only fire when `next()` is called in the
	// last handler in the chain and the route stack is of 
	// length 0
	cortex.on('afterRoute', function(route){
		console.log('after everything', route);

	// Define a middleware that will be used before every route
	cortex.use(function(route, next){ = 'test';

	// Define a route
	cortex.route('test/:token(/:optionalParam)', function(route, next){

	cortex.route('otherTest', {
		optionData: 'stuff'
	}, function(route, next){
		console.log('middleware 1');
	}, function(route, next){
		console.log('middleware 2');
	}, function(route, next){
		console.log('other test handler');

	// initialize your Backbone app
	var app = Backbone.Router.extend({
		routes: cortex.getRoutes(),
		initialize: function(){
			console.log('app init');

	new app();
	Backbone.history.start({ pushState: true });


The Cortex object prototype extends from Backbone.Events, so you are free to attach any event handlers you choose.


Cortex.prototype.use(function(route:obj[, next:function]){})

Much like the use function in Express, Cortex.prototype.use allows you to push a middleware onto the stack


is an object literal that contains some data that is passed along from handler to handler


An object containing a property for each query string parameter in the route. If there is no query string, it is the empty object, {}.


An object containing properties mapped to the named route “parameters”. For example, if you have the route user/:name, then the “name” property is available as This object defaults to {}.

An empty object where you can place data to be passed between handlers/middlewares


A reference to the Route object that encapsulates a given path/handler combination


An optional function that you can call to move on to the next handler. If the route stack is empty, the afterRoute will be fired.

If next is passed a truthy value, it will assume that you are passing an error and it will trigger the error event and stop execution of the route stack.


Creating a route is almost the same as registering a middleware:

Cortex.prototype.route(path[, options][, middlewares], handler)

The first parameter is a path definition as defined in the Backbone documentation:

Routes can contain parameter parts, :param, which match a single URL component between slashes; and splat parts *splat, which can match any number of URL components. Part of a route can be made optional by surrounding it in parentheses (/:optional).

For example, a route of search/:query/p:page will match a fragment of #search/obama/p2, passing "obama" and "2" to the action.

A route of file/*path will match #file/nested/folder/file.txt, passing nested/folder/file.txt to the action.

A route of docs/:section(/:subsection) will match #docs/faq and #docs/faq/installing, passing "faq" to the action in the first case, and passing "faq" and "installing" to the action in the second.

Trailing slashes are treated as part of the URL, and (correctly) treated as a unique route when accessed. docs and docs/ will fire different callbacks. If you can't avoid generating both types of URLs, you can define a docs(/) matcher to capture both cases.

Parameters specified in the URL are mapped and passed as the route.params object that is passed to the route handler.

The second parameter is an optional object literal that you can use to pass configuration data to your route. f Each of the middlewares and handler function are the same signature as the function passed to Cortex.prototype.use.


You can currently register two Backbone event handlers with your Cortex instance.

Cortex.prototype.on('error', function(err, route){})

When an exception is thrown while executing a handler or middleware, it is caught and passed to the on error event.


This is the error passed to the catch handler


Same as the route object passed to handlers.

Cortex.prototype.on('afterRoute', function(route){})

In the case that you want to have special logic run after your route is done executing, you can listen for the afterRoute event.

Note - this event will only fire if Cortex finds that the route stack is empty. To reach this state, next() must be called on the last handler/middleware in the stack.

Generating routes

Once you have your routes defined, calling Cortex.prototype.getRoutes() will return an object literal that can be passed as the routes value when creating a Backbone router.