A couchdb connector for backbone with support for real time changes.
JavaScript CoffeeScript
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 31 commits behind janmonschke:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
node couchapp chat example



This is a Backbone.js connector that overrides Backbone's default sync-behavior and connects your app to your CouchDB so that you can RELAX and don't need to worry about (real-time) server-side code.



  • 1.1

    • Fixed a bug with empty key param
  • 1.0

    • CoffeeScript rewrite
    • Support for custom filter functions
    • Chat example (including tests)
    • Backbone 5.1 support
    • Various bugfixes
    • Started versioning ;)

Dependencies (already included in the examples)

Why a new connector?

I developed this connector because I didn't want to write a whole new server that persists the models that Backbone.js creates. Instead of writing a server you now only have to write a simple design document containing one simple view and you're done with server-side code and can fully concentrate on the Backbone App.

Also I wanted to get real time updates when my models are changed on the server (e.g. by a second user). The CouchDB _changes feed seemed like a perfect match for this problem.

Getting Started

All Backbone apps should work normally without any changes. Simply include backbone-couchdb.js with its dependencies into your project and configure the connector with your database infos.

Backbone.couch_connector.config.db_name = "backbone-couchapp";
Backbone.couch_connector.config.ddoc_name = "backbone-couchapp";
Backbone.couch_connector.config.global_changes = false;

As you can see you also need to create a new database in your CouchDB and a new design document that contains the following view called "byCollection":

function(doc) {
    if (doc.collection) {
        emit(doc.collection, doc);

If you set Backbone.couch_connector.config.global_changes to true, the connector will automatically update your models with remote changes in near real time.

Give your couchapp some backbone

An easy way to host single-page apps is to enclose them in a couchapp. I included a sample couchapp project (/chat_example) to show you how to create couchapps with Backbone and this CouchDB connector. You can also use it as a bare couchapp directory structure for new projects.

There is an instance of this couchapp running on iriscouch.com (demo) and I uploaded a file with the annotated source of the app. (Created with docco)

Erica support

Erica templates are supported. Simply link the backbone-couchdb folder to ~/.erica/templates. Then you can create an application using these templates:

$ erica create template=backbone appid=myappname

Learn more

To show how backbone-couchdb works under the hood I created an annotated source file located here.