Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
302 lines (211 sloc) 10.8 KB

Rocket (node-rocket)

##The rapid development framework for node.js/couchDB/mongoDB real-time/comet web applications

Node Rocket Rocks! a.k.a. node-Rocket is a project created by Gabriel Lespérance during the “Startupfier Summer Kick-off: Hackathon” in order to allow rapid development of comet/real-time web applications using node.js and couchDB.

Highly inspired by Ruby on Rails and cakePHP, Rocket puts forward the convention over configuration principle in order to simplify and speedup the software development process and allow easier scalability by leveraging node.js asynchronous behavior as well as couchDB/mongoDB distributed natures.

Central to RocketJS is the principle of having a single point of contact between the programmer and the underlying application and resources. Hence, RocketJS aims to blur and reduce as much as possible the separation between the client (browser), the server (node.js) and the databases (couchDB/mongoDB) while maximizing the scaling potential (for instance by allowing code sharing between couchDB and the server, and between the server and the client) and improving the performance of the resulting web application.

Built on top of express -- node.js’ high performance web development framework -- RocketJS provides a robust structure on which to build your web applications without sacrificing any of your freedom.

RocketJS Features

  • Automatic routing of your controllers
  • Automatic mapping of your views to their corresponding controller
  • Automatic creation of your couchDB databases based on your models’ definitions
  • Automatic synchronization of your couchDB design documents with your server models
  • Automatic document validation based on your model’s schemas via couchDB validate_doc_update
  • Easy web-socket / comet application support through dnode
  • Easy server / client code sharing allowing the client to use CommonJS require() command to import/use server JS libraries
  • High focus on RESTful controller conventions
  • Rails-like form_tag and form_for form generation
  • View rendering and partials support
  • Connect middleware support
  • Built on top of express


$ npm install rocket


Usage: rocket [command] [argument(s)]

  -v, --version................................Prints RocketJS' version
  -h, --help...................................Prints this message
                                                 *** Use --kill to stop the server *** Used in conjunction with --start

  -I, --init [project name]....................Initialize project app
  -a, --add  [options].........................Add a [type] object to the current project working directory
                                                 do --info [type] for more info
  -i, --info [type]............................Prints usage information about [type] object

Available object types: controller 

Directory Structure of a Rocket Project

|-- client
|    # Contains all the files used by the client, including CSS, Javascript libraries and 
|    # static files.
|-- controllers
|    # Contains your application's controllers.
|-- exports
|    # Contains your application's modules that will be exported to the client. 
|-- models
|    # Contains all your applications's models and dataasources.
|-- plugins
|     # Contains all your application's plugins.
|-- views
|    # Contains your applications's main layout, template files and associated
|    # partials.
|- launcher.js


Structure of the Client directory

|-- libs
|    # Contains all the javascript files that are exported (through browserify)
|    # to the client. All these files can then be accessed via `require()`
|-- static
     # Contains all your static files.

Allow the browser to require() your javascript modules with ./client/libs/

Each files/folders located under the ./client/libs/ directory of your project are made available to the client's browser by Rocket via the require() command. The modules are referenced by their relative path from the ./client/libs/ folder.

e.g. To require a moduled located at ./clients/libs/a.js from the browser:

var a = require('./a');

The modules can also be located further down the ./client/libs directory tree. Hence you can require the file located at ./client/libs/nested/dirs/b.js by doing :

var myModuleFct = require('./client/libs/nested/dirs/b').myModuleFct;

Usual CommonJS conventions apply to the modules.

Serving static files via ./client/static

All files located under the ./client/static/ directory are statically served by Rocket under the URL.

Putting forth the use of conventions common to all Rocket projects, every project is initally created with the following files/dirs in ./client/static/:

|-- css
|-- font
|-- img
|-- apple-touch-icon.png
|-- favicon.ico


By using a modified version of the powerful express-resource plugin, Rocket provides you with a robust way of automatically mapping your controllers to your routes.

Each time you launch your application, Rocket takes all the ./controllers/[controller_name]_controller.js modules, and maps their exported functions as follows :

GET     /[controller_name]              ->  index
GET     /[controller_name]/new          ->  new
POST    /[controller_name]              ->  create
GET     /[controller_name]/:forum       ->  show
GET     /[controller_name]/:forum/edit  ->  edit
PUT     /[controller_name]/:forum       ->  update
DELETE  /[controller_name]/:forum       ->  destroy


GET     /forums              ->  require('./controllers/forums_controller').index
GET     /forums/new          ->  require('./controllers/forums_controller').new
POST    /forums              ->  require('./controllers/forums_controller').create
GET     /forums/:forum       ->  require('./controllers/forums_controller').show
GET     /forums/:forum/edit  ->  require('./controllers/forums_controller').edit
PUT     /forums/:forum       ->  require('./controllers/forums_controller').update
DELETE  /forums/:forum       ->  require('./controllers/forums_controller').destroy

Where {index, new, create, show, edit, update, destroy} are normal express callbacks functions :

function(req,res) { /* ... */ }

It is important to note that


is used as the / controller.

For more info see the express-resource readme.

Conventions on controller names

Controller names must :

  • be plural
  • be all lower case
  • be underscored
  • have a _controller suffix


  • ./controller/hyper_beams_controller.js

is valid whereas

  • ./controller/hyper_beams.js
  • and ./controller/hyper_beam_controller.js

are not.

Defining custom actions for your controllers

In cases where you might need to derive from the RESTful conventions, Rocket provides to you a way to add custom actions to your controllers by mapping any exported function but {index, new, create, show, edit, update, destroy} as follows:

{GET, POST, PUT, DELETE}  /[controller_name]/myAction  ->  myAction

You can also be more specific in your mapping by making myAction an object:

GET     /[controller_name]/myAction/    --\
        /[controller_name]/myAction/:id ---\-->  myAction.get

POST    /[controller_name]/myAction/    --\
        /[controller_name]/myAction/:id ---\-->

PUT     /[controller_name]/myAction/    --\
        /[controller_name]/myAction/:id ---\-->  myAction.put
DELETE  /[controller_name]/myAction/    --\
        /[controller_name]/myAction/:id ---\-->  myAction.destroy

Exporting functions of a controller without mapping them to a route

By default Rocket ignores all exported functions prefixed with an underscore _.

This can be used for example if you want to be able to require() and extend a base controller from which you want to inherit some property or methods.

Auto-loading resource for your controller

It is possible -- via express-resource -- to auto-load the data associated with a specific id for your controller to use.

Simply put, this can be done by exporting the function in question as_load in the controller module.

Auto-loading functions take the following form:

exports._load = function(id, cb) {
  var err
    , obj
  //(1) -- load the object with the specified id
  //(2) -- call the callback
  cb(err, obj);

For more info see express-resource readme.

Nesting controllers

You can nest controllers by leveraging app.rocket.controllers and the express-resource add function in your ./launcher.js file :

var rocket = require('rocket')
  , LISTEN_PORT = 80
  , app = rocket.createServer(__dirname)

//Nest the `children` controller under the `parents` controller.

Dnode exports

Exporting remote functions/objects to the client via ./exports/

Calling your exported functions from the client -- or browser.


Making worry free models using CouchDBResource

  • Automatically creates DB in accordance with
  • Automatically SYNC your _design documents (or views, lists, updates, shows, etc)
  • Automatically SYNC your _security document
  • Automatically validates your documents on the server using model.schema and validate_doc_update

Using model.schema to leverage Rocket automatic validation procedures

How to invoke your couchDB views

Creating your own validators using validate_doc_update

How to properly throw errors for the rocket form helper

Creating a datasource to keep it DRY !


Controller/Views mapping

bypassing view generation with XHR queries

Using the form_tag helper