A tool for building CouchDB documents from flat files.
Last updated 4 years ago by ezzatron .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install couchdb-builder 
SYNC missed versions from official npm registry.

CouchDB builder

A tool for building CouchDB documents from flat files.

Current version image Current build status image Current coverage status image

What does it do?

CouchDB builder recursively reads a directory of flat files in various formats, and builds a JSON document suitable for use with CouchDB. The most common application is for CouchDB design documents, that typically contain embedded code.


Command line usage

couchdb-builder <source-path> > <destination-path>

Module usage

CouchDB builder implements a promise-based interface:

var couchdbBuilder = require('couchdb-builder');
    function (result) {
        // handle result
    function (error) {
        // handle error

Supported file types

CouchDB builder supports various file types. The type is determined solely from the extension, and files with unsupported extensions are ignored:

Extension Type
.js CommonJS module (JavaScript)
.coffee CommonJS module (CoffeeScript)
.json JSON document
.txt text document
<none> text document

Example document

Given the following directory structure and file contents:


├── a/
│   ├── b
│   ├── c.txt
│   ├── d.json
│   └── e.other
└── views/
    ├── view-a/
    │   └── map.js
    └── view-b/


String content A.


String content B.


    "f": true,
    "g": 1.1




module.exports = function (doc) {


module.exports = (doc) ->
    emit doc._id


CouchDB builder will produce a document like the following:

    "a": {
        "b": "String content A.",
        "c": "String content B.",
        "d": {
            "f": true,
            "g": 1.1
    "views": {
        "view-a": {
            "map": "<source of map.js with wrapper>"
        "view-a": {
            "map": "<compiled source of with wrapper>"

Differences to couchdb-compile

Better support for CommonJS modules

Module support in couchdb-compile involves using .toString() on the module's exports. This does not mix well with some common patterns of CommonJS modules. Take the following module as an example:

var a = 'a';

module.exports = function () {
    return a;

Using .toString() on this module would result in the following code:

function () {
    return a;

Unfortunately, when this code is executed inside CouchDB, the variable a will be undefined, and hence the behavior has changed from the original module.

CouchDB builder takes a different approach, and instead surrounds the original source code in a light-weight wrapper. This wrapper allows the original code to function identically when used inside CouchDB, and when require'd as a CommonJS module.

The same module would look something like this when surrounded in the wrapper:

if (!module) { var module = {}; }

var a = 'a';

module.exports = function () {
    return a;


This works because CouchDB internally uses eval(), which returns the value of the last expression evaluated (i.e. module.exports).

Built-in support for CoffeeScript

CoffeeScript is not directly supported by couchdb-compile, although there is currently an open pull request designed to address this.

With CouchDB builder, CoffeeScript is automatically compiled to JavaScript, then surrounded with the same light-weight wrapper as any other JavaScript file. This means that CoffeeScript "just works" without any special configuration.

Although CouchDB does natively support CoffeeScript, it currently seems to re-compile on every execution. It is almost certainly more performant to compile once (it also simplifies the wrapper code).

Deterministic output

When generating JSON output, couchdb-compile internally uses JSON.stringify, which does not guarantee the order of properties in the output. If the resulting JSON is committed to a version control repository, this will sometimes produce "diff churn" (repeated commits to a file that do not change its content in a meaningful way).

CouchDB builder utilizes json-stable-stringify instead of JSON.stringify, to ensure that its output is deterministic (always the same, given the same input).

Unsupported features

The following features of couchdb-compile are not currently supported. Please open an issue if further discussion is warranted:

  • Attachments.
  • Automatic generation of the _id key. If no _id is specified, the document will not have one.
  • Special treatment of index.js or files as CommonJS modules. All .js and .coffee files are treated as modules in CouchDB builder.

Current Tags

  • 0.1.0                                ...           latest (4 years ago)

1 Versions

  • 0.1.0                                ...           4 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (4)
Dev Dependencies (9)
Dependents (1)

Copyright 2014 - 2016 © |