| layout | 2ColLeft |
|---|---|
| title | Custom Builds |
| sidebar | nav.html |
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 adapter
as its default adapter. 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-browserconst PouchDB = require('pouchdb-browser');
const db = new PouchDB('mydb');const PouchDB = require('pouchdb-core')
.plugin(require('pouchdb-adapter-idb'))
.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-nodeconst PouchDB = require('pouchdb-node');
const db = new PouchDB('mydb');const 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-coreconst 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.
The primary adapter used by PouchDB in the browser, using IndexedDB. The adapter
name is 'idb'.
npm install pouchdb-adapter-idbPouchDB.plugin(require('pouchdb-adapter-idb'));
const db = new PouchDB('mydb', {adapter: 'idb'});
console.log(db.adapter); // 'idb'An adapter used by PouchDB in the browser, using WebSQL. The adapter
name is 'websql'.
Before PouchDB 7.0.0, this was shipped as a default adapter. As of PouchDB 7.0.0, it must be loaded as a separate plugin.
npm install pouchdb-adapter-websqlPouchDB.plugin(require('pouchdb-adapter-websql'));
const db = new PouchDB('mydb', {adapter: 'websql'});
console.log(db.adapter); // 'websql'{% include alert/start.html variant="warning"%}
{% markdown %}
Warning: deprecation notice. The leveldb adapter will be deprecated in PouchDB version 10.0.0 and removed in version 11.0.0. You can read the migration guide here and more about the topic in this link.
{% endmarkdown %}
{% include alert/end.html%}
The primary adapter used by PouchDB in Node.js, using LevelDB. The adapter name
is 'leveldb'.
npm install pouchdb-adapter-leveldbPouchDB.plugin(require('pouchdb-adapter-leveldb'));
const 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-httpPouchDB.plugin(require('pouchdb-adapter-http'));
const db = new PouchDB('http://127.0.0.1:5984/mydb');
console.log(db.adapter); // 'http'{% include alert/start.html variant="warning"%}
{% markdown %}
Warning: deprecation notice. The memory adapter will be deprecated in PouchDB version 10.0.0 and removed in version 11.0.0. You can read the migration guide here and more about the topic in this link.
{% endmarkdown %}
{% include alert/end.html%}
An optional adapter that works in the browser and Node.js, fully in-memory. The adapter name
is 'memory'.
npm install pouchdb-adapter-memoryPouchDB.plugin(require('pouchdb-adapter-memory'));
const 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-localstoragePouchDB.plugin(require('pouchdb-adapter-localstorage'));
const 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-fruitdownPouchDB.plugin(require('pouchdb-adapter-fruitdown'));
const 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-websqlPouchDB.plugin(require('pouchdb-adapter-node-websql'));
const 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-indexeddbPouchDB.plugin(require('pouchdb-adapter-indexeddb'));
const 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-findPouchDB.plugin(require('pouchdb-find'));
const 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-mapreducePouchDB.plugin(require('pouchdb-mapreduce'));
const 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-replicationPouchDB.plugin(require('pouchdb-replication'));
const 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-mapreduceUtilities for PouchDB adapters.
npm install --save-exact pouchdb-adapter-utilsPouchDB's ajax() function.
npm install --save-exact pouchdb-ajaxUtilities for operating on binary strings and Buffers/Blobs.
npm install --save-exact pouchdb-binary-utilsTool to write a checkpoint, e.g. during replication.
npm install --save-exact pouchdb-checkpointerCollation functions for PouchDB map/reduce.
npm install --save-exact pouchdb-collateES6 shims for Map and Set as used in PouchDB.
npm install --save-exact pouchdb-collectionsErrors exposed by PouchDB.
npm install --save-exact pouchdb-errorsFunction to generate a replication ID to mark progress during replications.
npm install --save-exact pouchdb-generate-replication-idUtilities for safely stringifying and parsing JSON.
npm install --save-exact pouchdb-jsonUtilities used by pouchdb-mapreduce.
npm install --save-exact pouchdb-mapreduce-utilsUtilities for calculating MD5 checksums.
npm install --save-exact pouchdb-md5PouchDB's CouchDB-style document merge algorithm.
npm install --save-exact pouchdb-mergeA Promise object, polyfilled using lie if Promises aren't available globally.
npm install --save-exact pouchdb-promiseThe 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-coreA potpourri of miscellaneous utilities used by PouchDB and its sub-packages.
npm install --save-exact pouchdb-utilsFork of level-sublevel with only the subset of the API that PouchDB uses.
npm install --save-exact sublevel-pouchdb