{% include anchor.html edit="true" title="Plugins" hash="plugins" %}
Writing a plugin is easy! The API is:
{% highlight js %}
PouchDB.plugin({
methodName: myFunction
});
{% endhighlight %}
This will add a `db.methodName()` to all databases, which runs `myFunction`.It will always be called in context, so that within the function, `this` refers to the database object.
There is a [PouchDB Plugin Seed project](https://github.com/pouchdb/plugin-seed), which is the fastest way to get started writing, building and testing your very own plugin.
#### Example Usage:
{% highlight js %}
PouchDB.plugin({
sayHello : function () {
console.log("Hello!");
}
});
new PouchDB('foobar').sayHello(); // prints "Hello!"
{% endhighlight %}
#### Load Plugins from require()
You can load plugins into PouchDB when you load it via `require()`.
{% highlight js %}
var greet = {sayHello: function() { console.log("Hello!"); }};
var PouchDB = require('pouchdb').plugin(greet);
var db = new PouchDB('foobar');
db.sayHello(); // prints "Hello!"
{% endhighlight %}
You can chain plugins, as well:
{% highlight js %}
var greet = {sayHello: function() { console.log("Hello!"); }};
var manners = {thank: function(name) { console.log("Thank you, " + name); }};
var PouchDB = require('pouchdb')
.plugin(greet)
.plugin(manners);
var db = new PouchDB('foobar');
db.sayHello(); // prints "Hello!"
db.thank('Mom'); // prints "Thank you, Mom"
{% endhighlight %}
#### Example Plugin: Intercept Updates
A useful feature of plugins is to intercept updates before they are stored in PouchDB. In this way, a plugin might validate that the data is correct for the application, or even alter documents before they are committed to the database.
The best way to intercept all updates to a PouchDB database is to **override the `bulkDocs()` method**. All changes to PouchDB documents ultimately pass through the `bulkDocs()` method. For example, a call to `put()` will become become a `bulkDocs()` call with a "batch" of one document.
Because PouchDB guarantees to plugin authors that all data changes ultimate happen via `bulkDocs()`, it is the ideal place for an application or plugin to intercept updates.
{% highlight js %}
// Keep a reference to the "upstream" function.
var pouchBulkDocs = PouchDB.prototype.bulkDocs;
PouchDB.plugin({bulkDocs: validBulkDocs});
function validBulkDocs(body, options, callback) {
if (typeof options == 'function') {
callback = options
options = {}
}
if (Array.isArray(body)) {
var docs = body;
} else {
var docs = body.docs;
}
// All documents must have a .name field.
for (var i = 0; i < docs.length; i++) {
if (!docs[i].name) {
var id = doc._id || '(no _id given)';
return callback(new Error('Document is missing .name field: ' + id));
}
}
// All documents check out. Pass them to PouchDB.
return pouchBulkDocs.call(this, docs, options, callback);
}
{% endhighlight %}
The above plugin would return an error if anything ever attempts to store an unnamed document, including documents which change during replication.
Note: this is a very, very simple validation example. It does not behave, for example, like the Apache CouchDB `validate_doc_update()` API.