PouchDB supports custom builds, meaning you can pick and choose the features of PouchDB that you want to use, potentially resulting in smaller bundle sizes and faster build times.
PouchDB exposes its custom builds via separate packages available on npm. All of these packages follow the format pouchdb-<name> and can be installed using npm install.
Some packages are included by default in the main pouchdb package, whereas others (including third-party packages) must be installed separately.
{% include alert/start.html variant=“warning”%} {% markdown %}
Custom builds require an npm-based build system, using a bundler like Browserify, Webpack, SystemJS, Rollup, or JSPM. Tools like Bower, as well as direct download of prebuilt JavaScript files, are not supported.
{% endmarkdown %} {% include alert/end.html%}
PouchDB packages come in three flavors: presets, plugins, and utilities.
Presets are a collection of plugins, which expose a PouchDB object that is ready to be used.
Plugins are features that can be added to a PouchDB instance using the PouchDB.plugin() API.
Utilities are grab-bags of helper functions, and are only recommended for advanced use cases.
{% include anchor.html class=“h2” title=“Presets” hash=“presets” %}
Presets export a PouchDB object and contain a built-in set of PouchDB plugins. You are free to create your own presets, but PouchDB provides a few first-party presets to address common use cases.
The pouchdb-browser preset contains the version of PouchDB that is designed for the browser. In particular, it ships with the IndexedDB and WebSQL adapters as its default adapters. It also contains the replication, HTTP, and map/reduce plugins.
Use this preset if you only want to use PouchDB in the browser, and don't want to use it in Node.js. (E.g. to avoid installing LevelDB.)
npm install pouchdb-browser
var PouchDB = require('pouchdb-browser'); var db = new PouchDB('mydb');
var PouchDB = require('pouchdb-core') .plugin(require('pouchdb-adapter-idb')) .plugin(require('pouchdb-adapter-websql')) .plugin(require('pouchdb-adapter-http')) .plugin(require('pouchdb-mapreduce')) .plugin(require('pouchdb-replication'));
The pouchdb-node preset contains the version of PouchDB that is designed for Node.js. In particular, it uses the LevelDB adapter and doesn't ship with the IndexedDB or WebSQL adapters. It also contains the replication, HTTP, and map/reduce plugins.
Use this preset if you are only using PouchDB in Node, and not in the browser.
npm install pouchdb-node
var PouchDB = require('pouchdb-node'); var db = new PouchDB('mydb');
var PouchDB = require('pouchdb-core') .plugin(require('pouchdb-adapter-leveldb')) .plugin(require('pouchdb-adapter-http')) .plugin(require('pouchdb-mapreduce')) .plugin(require('pouchdb-replication'));
The pouchdb-core package is a special preset in that it exposes the minimum number of APIs. It contains zero plugins and is designed to be used in addition with other plugins. By itself, it probably isn't very useful.
npm install pouchdb-core
var PouchDB = require('pouchdb-core'); PouchDB.plugin(/* attach plugins to make me more interesting! */);
{% include anchor.html class=“h2” title=“Plugins” hash=“plugins” %}
Plugins contain functionality that can be added to a PouchDB instance using PouchDB.plugin(). There are many third-party plugins, but the ones described below are first-party plugins, which are given the same level of support as PouchDB itself. Some first-party plugins are included in the default pouchdb build, whereas others aren't.
There is also a special type of plugin called an adapter plugin. Adapter plugins (such as IndexedDB, WebSQL, LevelDB, and HTTP) determine the storage format that PouchDB uses. For the non-HTTP adapters, the plugin order matters, i.e. if you want IndexedDB to be preferred to WebSQL, then you should load it first. (Notice that pouchdb-browser does exactly this.)
The primary adapter used by PouchDB in the browser, using IndexedDB. The adapter name is 'idb'.
npm install pouchdb-adapter-idb
PouchDB.plugin(require('pouchdb-adapter-idb')); var db = new PouchDB('mydb', {adapter: 'idb'}); console.log(db.adapter); // 'idb'
The secondary adapter used by PouchDB in the browser, using WebSQL. The adapter name is 'websql'.
npm install pouchdb-adapter-websql
PouchDB.plugin(require('pouchdb-adapter-websql')); var db = new PouchDB('mydb', {adapter: 'websql'}); console.log(db.adapter); // 'websql'
The primary adapter used by PouchDB in Node.js, using LevelDB. The adapter name is 'leveldb'.
npm install pouchdb-adapter-leveldb
PouchDB.plugin(require('pouchdb-adapter-leveldb')); var db = new PouchDB('mydb', {adapter: 'leveldb'}); console.log(db.adapter); // 'leveldb'
The primary adapter used by PouchDB in both Node.js and the browser for communicating with external CouchDB (or CouchDB-like) servers.
This plugin can be added to PouchDB in any order, and is somewhat special in that you must pass in a name like 'http://...' in order to use it. The adapter name is either 'http' or 'https' depending on the protocol.
npm install pouchdb-adapter-http
PouchDB.plugin(require('pouchdb-adapter-http')); var db = new PouchDB('http://127.0.0.1:5984/mydb'); console.log(db.adapter); // 'http'
An optional adapter that works in the browser and Node.js, fully in-memory. The adapter name is 'memory'.
npm install pouchdb-adapter-memory
PouchDB.plugin(require('pouchdb-adapter-memory')); var db = new PouchDB('mydb', {adapter: 'memory'}); console.log(db.adapter); // 'memory'
An optional adapter that works in the browser using LocalStorage. The adapter name is 'localstorage'.
npm install pouchdb-adapter-localstorage
PouchDB.plugin(require('pouchdb-adapter-localstorage')); var db = new PouchDB('mydb', {adapter: 'localstorage'}); console.log(db.adapter); // 'localstorage'
An optional adapter that works in the browser using IndexedDB via fruitdown. The adapter name is 'fruitdown'.
npm install pouchdb-adapter-fruitdown
PouchDB.plugin(require('pouchdb-adapter-fruitdown')); var db = new PouchDB('mydb', {adapter: 'fruitdown'}); console.log(db.adapter); // 'fruitdown'
An optional adapter that works in Node.js using SQLite via node-websql. The adapter name is 'websql'.
npm install pouchdb-adapter-node-websql
PouchDB.plugin(require('pouchdb-adapter-node-websql')); var db = new PouchDB('mydb', {adapter: 'websql'}); console.log(db.adapter); // 'websql'
{% include alert/start.html variant=“warning”%} {% markdown %}
Warning: experimental. You probably don't want to use this yet. 😉
{% endmarkdown %} {% include alert/end.html%}
An experimental next-generation IndexedDB adapter, also known as “idb-next”. Currently not shipped as part of PouchDB. The adapter name is 'indexeddb'.
npm install pouchdb-adapter-indexeddb
PouchDB.plugin(require('pouchdb-adapter-indexeddb')); var db = new PouchDB('mydb', {adapter: 'indexeddb'}); console.log(db.adapter); // 'indexeddb'
PouchDB's “Mango” query API, exposed via the find(), listIndexes(), createIndex(), and deleteIndex()` methods. Not shipped by default in PouchDB.
npm install pouchdb-find
PouchDB.plugin(require('pouchdb-find')); var db = new PouchDB('mydb'); db.find(/* see API docs for full info */);
PouchDB's map/reduce API, exposed via the query() and viewCleanup() methods. Ships by default in PouchDB.
npm install pouchdb-mapreduce
PouchDB.plugin(require('pouchdb-mapreduce')); var db = new PouchDB('mydb'); db.query(/* see query API docs for full info */);
PouchDB's replication API, exposed via the replicate() and sync() methods. Ships by default in PouchDB.
npm install pouchdb-replication
PouchDB.plugin(require('pouchdb-replication')); var db = new PouchDB('mydb'); db.replicate(/* see replicate/sync API docs for full info */);
{% include anchor.html class=“h2” title=“Utilities” hash=“utilities” %}
These utilities are intended only for advanced users of PouchDB, such as third-party plugin authors. Formerly, many of them were exposed via the extras/ API, which is now deprecated.
Most of these are internal, and the APIs are not thoroughly documented. You will most likely need to read the source code to understand how they work.
{% include alert/start.html variant=“warning”%} {% markdown %}
Warning: you are entering a semver-free zone.
In contrast to the presets and plugins listed above, none of the following packages follow semver. Their versions are pinned to PouchDB's, and may change at any time without warning. You are strongly recommended to use exact versions when installing these packages.
{% endmarkdown %} {% include alert/end.html%}
The underlying logic for secondary indexes, as expressed in both pouchdb-mapreduce and pouchdb-find. Both packages use this package under the hood.
npm install --save-exact pouchdb-abstract-mapreduce
Utilities for PouchDB adapters.
npm install --save-exact pouchdb-adapter-utils
PouchDB's ajax() function.
npm install --save-exact pouchdb-ajax
Utilities for operating on binary strings and Buffers/Blobs.
npm install --save-exact pouchdb-binary-utils
Tool to write a checkpoint, e.g. during replication.
npm install --save-exact pouchdb-checkpointer
Collation functions for PouchDB map/reduce.
npm install --save-exact pouchdb-collate
ES6 shims for Map and Set as used in PouchDB.
npm install --save-exact pouchdb-collections
The PouchDB.debug() API, expressed as a separate plugin. May eventually be removed from PouchDB core.
npm install --save-exact pouchdb-debug
Errors exposed by PouchDB.
npm install --save-exact pouchdb-errors
Function to generate a replication ID to mark progress during replications.
npm install --save-exact pouchdb-generate-replication-id
Utilities for safely stringifying and parsing JSON.
npm install --save-exact pouchdb-json
Utilities used by pouchdb-mapreduce.
npm install --save-exact pouchdb-mapreduce-utils
Utilities for calculating MD5 checksums.
npm install --save-exact pouchdb-md5
PouchDB's CouchDB-style document merge algorithm.
npm install --save-exact pouchdb-merge
A Promise object, polyfilled using lie if Promises aren't available globally.
npm install --save-exact pouchdb-promise
The core Mango selector logic, which allows the selector to be used both by pouchdb-find and for filtering/replication.
npm install --save-exact pouchdb-selector-core
A potpourri of miscellaneous utilities used by PouchDB and its sub-packages.
npm install --save-exact pouchdb-utils
Fork of level-sublevel with ony the subset of the API that PouchDB uses.
npm install --save-exact sublevel-pouchdb