Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including blue-router with all npm packages installed. Try it out:

var blueRouter = require("blue-router")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

blue-router v1.2.10

Universal router powered by Bluebird promises.

Blue Router

Blue Router is router powered by Bluebird promises. Routing is process that determines which function will be executed on the fly. Decision depends on URI. For example: context.uri = '/user/register' will execute user registration function.

Blue Router can be used in NodeJS HTTP server, TCP server, UDP server, Redis PUB/SUB, browser side ...etc.

It's really universal and very fast.


npm install blue-router --save


The only dependency is Bluebird package. The advantage is in rich Bluebird API methods.

const Promise = require('bluebird') //NodeJS or Browserify
<script src="bluebird.min.js"></script> //Browser (client side)


//NodeJS or browserify (client side)
const br = require('blue-router');

//Browser (client side)
<script src="bluebird.min.js"></script>
<script src="/blue-router/index.js"></script>


  • br(context).when(route) when 'context.uri' is matched against 'route' function in then() is executed
  • br(context).when(route1).redirect(route2) will redirect from 'route1' to 'route2'
  • br(context).notfound() 404 not found. Always put this method after all when() methods.
  • br(context).do() will be executed on each request

All methods when(), redirect(), notfound(), do() return bluebird promise and after that you can use any of bluebird methods (then, spread, catch, delay ...)


Trailing and ending slashes can be ignored so all of these URIs will be valid:


Case Insensitive URIs

URIs are case insensitive so all of these URIs will work:


Regular Expressions in route definition

RegExp syntax is allowed in route definition.

  • . any character
  • * match 0 or more times
  • + match 1 or more times
  • ? match 0 or 1 time
  • | alternative
  • () grouping
  • [] set of chars
  • {m, n} repetition modifier (at least m but at most n)
  • \\w word
  • \\W non-word
  • \\d digit
  • \\D non-digit
  • ... and others


Variables in Blue Router are named simmilar to ExpressJS:

  • ctx.req.body for example context.req.body = {name: 'Peter'}
  • ctx.req.params for example /user/:id and /user/23 will return {id: 23}
  • ctx.req.query for example ?username=john&password=as1234 will return {username: 'john', password: 'as1234'}


Use Bluebird then() to serially connect functions. This will make your code more readable and error handling easier. br(context).when(route).then(func11).then(func12).then(func13).catch(logErr)

Error 404: Not Found

Method notfound() must be placed after all when() methods.

br(context).notfound().then(function (ctx) {console.log('Error 404: ROUTE ' + ctx.uri + ' NOT FOUND');}).catch(errLog)


To activate Blue Router debugging set context.opts.debug: true


NodeJS server (HTTP, TCP, UDP, Redis channel)

 * TCP server example
const br = require('blue-router');

//cmd value can be changed dynamically by TCP server
var input = {cmd: '/register/john/45', data: {company: 'Cloud LLC', employers: 257}};

var context = {
    uri: input.cmd,
    req: {
    res: {
        socket: socket

// br(context).when() is Bluebird promise
// 'ctx' is 'context' object with added req.query and req.params properties
    .then(function (ctx) {
        console.log('ctx.req.query: ', ctx.req.query); //undefined
        console.log('ctx.req.params: ', ctx.req.params); //{name: 'John', age: 45}
        console.log('ctx.req.body: ', ctx.req.body); //{company: 'Cloud LLC', employers: 257}

        ctx.res.socket.write('Message to TCP client.');
    .catch(function (err) {

Explanation: br(context).when() makes Bluebird promise and after that you can use all bluebird's API methods. URI 'context.uri' can be fetched dynamically from browser's URL, HTTP/TCP/UDP server request or from command line (CLI).


const br = require('blue-router');
var errLog = require('./cli/errLog.js');

//input from console - cli input ($node cli.js {"cmd":"/cli/register/john/23/true","data":{}})
var input = process.argv[2];

//converting a string to object
try {
    input = JSON.parse(input); //convert string to object
} catch (err) {

//context object which define router behaviour
var context = {
    uri: input.cmd,
    req: {
    res: {
        cl: console.log
    opts: {
        debug: false

///////////// R O U T E S /////////////////////


//node cli.js '{"cmd": "/cli/list", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'  --> run this in Linux terminal
//node cli.js '{"cmd": "/cli/list/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
//node cli.js '{"cmd": "cli/list", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
//node cli.js '{"cmd": "cli/list/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'

/// redirection
//node cli.js '{"cmd": "/cli/listall", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
//node cli.js '{"cmd": "/cli/listall/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
//node cli.js '{"cmd": "cli/listall", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
//node cli.js '{"cmd": "cli/listall/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'

//node cli.js '{"cmd": "/cli/getname/firstname", "data": {"name": "Sasa"}}'
//node cli.js '{"cmd": "/cli/getname/firstname/", "data": {"name": "Sasa"}}'
//node cli.js '{"cmd": "cli/getname/firstname", "data": {"name": "Sasa"}}'
//node cli.js '{"cmd": "cli/getname/firstname/", "data": {"name": "Sasa"}}'

////examples with uri query string
//node cli.js '{"cmd": "/cli/login?username=peter&password=pan", "data": {}}'
//node cli.js '{"cmd": "/cli/login/?username=peter&password=pan", "data": {}}'
//node cli.js '{"cmd": "cli/login?username=peter&password=pan", "data": {}}'
//node cli.js '{"cmd": "cli/login/?username=peter&password=pan", "data": {}}'

////examples with regular expression
//node cli.js '{"cmd": "/cli/getnames/12345", "data": {"name": "McCloud"}}'
//node cli.js '{"cmd": "/cli/getnames/12345/", "data": {"name": "McCloud"}}'
//node cli.js '{"cmd": "cli/getnames/12345", "data": {"name": "McCloud"}}'
//node cli.js '{"cmd": "cli/getnames/12345/", "data": {"name": "McCloud"}}'
//node cli.js '{"cmd": "/cli/getname/12/", "data": {"name": "McCloud"}}'


//node cli.js '{"cmd": "/cli/users/55", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
//node cli.js '{"cmd": "/cli/users/55/", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
//node cli.js '{"cmd": "cli/users/55", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
//node cli.js '{"cmd": "cli/users/55/", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'

//node cli.js '{"cmd": "/cli/register/john/23/true", "data": {"nick": "johnny"}}'
//node cli.js '{"cmd": "/cli/register/john/23/true/", "data": {"nick": "johnny"}}'
//node cli.js '{"cmd": "cli/register/john/23/true", "data": {"nick": "johnny"}}'
//node cli.js '{"cmd": "cli/register/john/23/true/", "data": {"nick": "johnny"}}'
//examples with uri query string
//node cli.js '{"cmd": "/cli/register/john/23/true?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
//node cli.js '{"cmd": "/cli/register/john/23/true/?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
//node cli.js '{"cmd": "cli/register/john/23/true?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
//node cli.js '{"cmd": "cli/register/john/23/true/?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'

///examples with regular expression

//node cli.js '{"cmd": "/cli/shops/www/CloudShop/1971", "data": {}}'
//node cli.js '{"cmd": "/cli/shop/www/CloudShop/1971", "data": {}}'

//\\d+ replaces one or more digits (integer numbers)
//node cli.js '{"cmd": "/cli/shop/5/BetaShop/1978/red", "data": {}}'
//node cli.js '{"cmd": "/cli/shop/567/BetaShop/1978/red", "data": {}}'

///// NO MATCH (bad uri - Error 404)

//node cli.js '{"cmd": "", "data": {}}'
//node cli.js '{"cmd": "/", "data": {}}'
//node cli.js '{"cmd": "/cli", "data": {}}'
//node cli.js '{"cmd": "/cli/", "data": {}}'
//node cli.js '{"cmd": "/cli/lis", "data": {}}'
//node cli.js '{"cmd": "/cli/lista", "data": {}}'
//node cli.js '{"cmd": "/cli/list/bad", "data": {}}'
br(context).notfound().then(require('./cli/notfound.js')).catch(errLog); //put this after all when() methods

//always will be executed on each URI

Error Handling

========= errLog.js ==========
// print only messages where err.message is not empty string
module.exports = (err) => {
  if (!!err && !!err.message) {
    console.log('errLog: ', err.stack);


Copyright (c) 2017 Saša Mikodanić Licensed under MIT .

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free