Web framework for Node.js
Pull request Compare This branch is even with geddy:0.2-refactor.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Geddy web framework for Node.js


  • Easy to use
  • Modular
  • Fast

Geddy should make things easy for the most basic applications, but still let you get under the hood and tinker if you want.


  • Powerful, flexible router
  • Easy resource-based routing
  • App and resource generators
  • Content-negotiation
  • Session support (in-memory, cookie, CouchDB)
  • Templating (EJS), partials support
  • Fully non-blocking


Apache License, Version 2


Geddy requires version 0.4.x or higher of Node.js, and the Jake JavaScript build-tool.


To get Geddy from GitHub and install it:

git clone git://github.com/mde/geddy.git
cd geddy
make && sudo make install

Installing with NPM

npm install -g geddy

Geddy includes app- and resource-generation scripts that are easiest to use in a global install.


Routes are similar to Merb or Rails routes.

Basic routes

  {controller: 'Moving', action: 'pictures'});

   {controller: 'Farewells', action: 'kings'});

//Can also match specific HTTP methods only
router.match('/xandadu', 'get').to(
  {controller: 'Xandadu', action: 'specialHandler'});

Resource-based routes


Creating a Geddy app

You can use Geddy to create an app. Run geddy app [app-name] to create an app. Then Run geddy inside the app-directory to start the server.

mde@localhost:~/work$ geddy app bytor
Created app bytor.
mde@localhost:~/work$ cd bytor
mde@localhost:~/work/bytor$ geddy
Server running at

Go to http://localhost:4000/, and you should see:

Attention all planets of the Solar Federation

Adding resources

Use geddy resource in your app directory to add a resource. The route will be set up automatically for you.

mde@localhost:~/work/bytor$ geddy-gen resource snow_dog
[ADDED] ./app/models/snow_dog.js
[ADDED] ./app/controllers/snow_dogs.js
resources snow_dogs route added to ./config/router.js
Created view templates.

Restart Geddy, and you'll see the new route working. Hit your new route -- for example, http://localhost:4000/snow_dogs.json, and you should see something like this:


The geddy generator utility also handles fancy pluralization between model and controller. Specify your resource-name as a singular naun, and the generator will do the right thing -- changing 'person' to 'people,' etc.

App layout

After adding a resource, a Geddy app is laid out like this:

mde@localhost:~/work/bytor$ find .

Resources and controllers

Geddy's resource-based routes create url/request-method mappings for easy CRUD operations like this:

GET */snow_dogs[.extension]
(SnowDogs controller, index action)

GET */snow_dogs/add[.extension]
(SnowDogs controller, add action, for any new-resource template -- "new" is not usable as a JavaScript action name)

POST */snow_dogs[.extension]
(SnowDogs controller, create action)

GET */snow_dogs/:id[.extension]
(SnowDogs controller, show action)

GET */snow_dogs/:id/edit[.extension]
(SnowDogs controller, edit action)

PUT */snow_dogs/:id[.extension]
(SnowDogs controller, update action)

DELETE */snow_dogs/:id[.extension]
(SnowDogs controller, remove action)

A simple controller that just responds with any form-post/query-string params looks like this:

var SnowDogs = function () {
  this.respondsWith = ['text', 'json', 'html'];

  this.index = function (params) {
    this.respond({params: params});

  this.add = function (params) {
    this.respond({params: params});

  this.create = function (params) {
    this.respond({params: params});

  this.show = function (params) {
    this.respond({params: params});

  this.update = function (params) {
    this.respond({params: params});

  this.remove = function (params) {
    this.respond({params: params});


exports.SnowDogs = SnowDogs;


Geddy has built-in ability to perform content-negotiation based on the requested filename-extension.

If you have a JSON-serializable JavaScript object you want to return in JSON format, pass your JavaScript object to the respond method in the action on that controller.

this.respondsWith = ['text', 'json'];

this.show = function (params) {
  // (Fetch some item by params.id)
    item = {foo: 'FOO', bar: 1, baz: false};

Models and validations

Geddy has an easy, intuitive way of defining models, with a full-featured set of data validations. The syntax is very similar to models in Ruby's ActiveRecord or DataMapper.

The model module is coded with browser-based use in mind, so it's very easy to share model and input validation code in your app between client and server.

Here is an example of a model with some validations:

var User = function () {
  this.property('login', 'string', {required: true});
  this.property('password', 'string', {required: true});
  this.property('lastName', 'string');
  this.property('firstName', 'string');

  this.validatesFormat('login', /[a-z]+/, {message: 'Subdivisions!'});
  this.validatesLength('login', {min: 3});
  this.validatesConfirmed('password', 'confirmPassword');
  this.validatesWithFunction('password', function (s) {
      // Something that returns true or false
      return s.length > 0;

  // Can define methods for instances like this
  this.someMethod = function () {
    // Do some stuff

// Can also define them on the prototype
User.prototype.someOtherMethod = function () {
  // Do some other stuff

geddy.model.registerModel('User', User);

Creating an instance of one of these models is easy:

var params = {
  login: 'alex',
  password: 'lerxst',
  lastName: 'Lifeson',
  firstName: 'Alex'
var user = User.create(params);

Data-validation happens on the call to create, and any validation errors show up inside an errors property on the instance, keyed by field name. Instances have a valid method that returns a Boolean indicating whether the instance is valid.

// Leaving out the required password field
var params = {
  login: 'alex',
var user = User.create(params);

// Prints 'false'
// Prints 'Field "password" is required'

API Docs

API docs can be found here.

Geddy Web-app development framework copyright 2112 mde@fleegix.org.