grunt-couch

Compile CouchDB design documents from Couchapp like directory tree.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-couch --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-couch');

The "couch-compile" task

Process Couchapp directoriy trees, JSON files and JavaScript modules.

Overview

In your project's Gruntfile, add a section named couch-compile to the data object passed into grunt.initConfig().

grunt.initConfig({
  'couch-compile': {
    app: {
      files: {
        'tmp/app.json': 'couch/*'
      }
    }
  }
})

This will load the directory tree from app and creates an app.json JSON file.

See Configuring tasks: Files for more information about possible source and target configurations.

Options

options.merge

Your can specify sources which will be merged into all docs. This is useful to provide defaults like templates and libs which are used in all ddocs.

Eg:

grunt.initConfig({
  'couch-compile': {
    app: {
      config: {
        merge: 'couch/shared/*'
      },
      files: {
        'tmp/app.json': 'couch/*'
      }
    }
  }
})

Merge sources are expanded via grunt.file.expand and compiled in exactly the same way as the other couch-compile targets.

The Couch Directory Tree

is quite self-explanatory. For example:

app
├── _attachments
│   ├── a
│   │   └── nested
│   │       └── file.txt
│   └── index.html
├── _id
├── language
├── lists
│   └── docs.js
├── rewrites.json
├── shows
│   ├── doc.js
│   └── hello.js
├── validate_doc_update.js
└── views
    ├── names
    │   └── map.js
    └── numbers
        ├── map.js
        └── reduce

grunt-couch uses a filesystem mapping similar to Couchapp python tool and Erika.

grunt-couch is based on couch-compile.

For the property name the file extension will be stripped:

{
  "validate_doc_update": "content of validate_doc_update.js",
}

Files inside the \_attachments directory are handled special: They become attachment entries of the form

{
  "a/nested/file.txt": {
    "data": "SGVsbG8gV29ybGQhCg==",
    "content_type": "text/plain"
  }
}

The content\_type is quessed using mime. data is the base64 encoded value of the file.

Read more about the so called Inline Attachments.

Output JSON

The output JSON follows the Bulk Document API:

{
  "docs": [
    { "_id": "adoc" },
    { "_id": "anotherdoc" }
  ]
}

The "couch-push" task

With the couch-push task you deploy your documents to CouchDB.

The database is created if not already present.

Overview

In your project's Gruntfile, add a section named couch-push to the data object passed into grunt.initConfig().

grunt.initConfig({
  'couch-push': {
    options: {
      user: 'karin',
      pass: 'secure'
    },
    localhost: {
      files: {
        'http://localhost:5984/myapp': 'tmp/app.json'
      }
    }
  }
})

Options

You may also pass in all the options as command line arguments and avoid storing the auth credentials in your gruntfile.

options.user

Your username.

options.pass

Your password.

The "couch" task

This is an Alias task for couch-compile and couch-push. It first compiles and then pushs the documents.

The "couch-configure" task

You can write CouchDB configuration from project files with couch-configure.

This comes in handy when you are using Virtual Hosts or when your app requires custom configuration options in order to work.

Overview

In your project's Gruntfile, add a section named couch-configure to the data object passed into grunt.initConfig().

grunt.initConfig({
  'couch-configure': {
    options: {
      user: 'karin',
      pass: 'secure'
    },
    localhost: {
      files: {
        'http://localhost:5984': 'config'
      }
    }
  }
})

Now write your configuration options in plain files, eg:

config/
└── vhosts
    └── myapp.localhost

Options

You may also pass in all the options as command line arguments and avoid storing the auth credentials in your gruntfile.

options.user

Your username.

options.pass

Your password.

The "couch-security" task

You can write CouchDB _security Objects from project files with couch-security.

Overview

In your project's Gruntfile, add a section named couch-security to the data object passed into grunt.initConfig().

grunt.initConfig({
  'couch-security': {
    options: {
      user: 'karin',
      pass: 'secure'
    },
    localhost: {
      files: {
        'http://localhost:5984/mydb': 'couch/mydb/security.json'
      }
    }
  }
})

Options

You may also pass in all the options as command line arguments and avoid storing the auth credentials in your gruntfile.

options.user

Your username.

options.pass

Your password.

The "couch-replication" task

You can write CouchDB _replicator Documents from project files with couch-replication.

If there is already a replication document, it will gets deleted and recreated, which causes the replication to restart.

Overview

In your project's Gruntfile, add a section named couch-replication to the data object passed into grunt.initConfig().

grunt.initConfig({
  'couch-replication': {
    options: {
      user: 'karin',
      pass: 'secure'
    },
    localhost: {
      files: {
        'http://localhost:5984': 'couch/replications/*.json'
      }
    }
  }
})

Options

You may also pass in all the options as command line arguments and avoid storing the auth credentials in your gruntfile.

options.user

Your username.

options.pass

Your password.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.