Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    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.


    npm i couchdb-builder

    Downloadsweekly downloads








    last publish


    • avatar