pouchdb-node

library9.0.0jsnpmunverified

PouchDB-node is the specialized Node.js distribution of PouchDB, a JavaScript database inspired by Apache CouchDB. It enables developers to store, query, and sync data offline in Node.js environments. Unlike the full PouchDB build, `pouchdb-node` is optimized for server-side use, utilizing LevelDB for local storage and omitting browser-specific adapters like IndexedDB or WebSQL. The current stable version is 9.0.0, released in late 2025/early 2026. Major versions are released periodically (e.g., 7.0.0, 8.0.0, 9.0.0), often introducing significant architectural changes like moving to modern ES6+ syntax or internal refactors. Patch releases are more frequent, addressing bugs and dependency updates. Its key differentiator is its Node.js-first approach, bundling core features like replication, HTTP, and map/reduce without browser bloat.

database

npm install pouchdb-node

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POUCHDB-NODE

pouchdb-node

databasejavascriptv9.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PouchDB

✓ import PouchDB from 'pouchdb-node';

✗ const PouchDB = require('pouchdb-node').default;

Since PouchDB 8.x, the library embraces ES6+ syntax, favoring default ESM imports. CommonJS `require` still works but might be less idiomatic for newer projects.

PouchDB (CommonJS)

✓ const PouchDB = require('pouchdb-node');

✗ import PouchDB from 'pouchdb-node';

This is the classic CommonJS `require` pattern for Node.js, which is still fully supported. If you're in an ESM project, use the `import` syntax.

PouchDB.plugin

✓ import PouchDB from 'pouchdb-node'; PouchDB.plugin(require('my-pouchdb-plugin'));

✗ import { plugin } from 'pouchdb-node';

Plugins are typically applied directly to the PouchDB constructor via `PouchDB.plugin()`. `pouchdb-node` includes common plugins like replication and map/reduce by default, but external ones need explicit loading.

This quickstart demonstrates how to initialize a PouchDB database in Node.js using `pouchdb-node`, create, read, update, and delete a document, and finally destroy the database. It uses a temporary directory for storage.

import PouchDB from 'pouchdb-node'; import path from 'path'; import os from 'os'; const dbPath = path.join(os.tmpdir(), 'my_pouchdb_database'); const db = new PouchDB(dbPath); async function runExample() { try { // Create a document const doc = { _id: 'mydoc', name: 'My Test Document', value: Math.random() }; const response = await db.put(doc); console.log('Document created:', response); // Get the document const fetchedDoc = await db.get('mydoc'); console.log('Document fetched:', fetchedDoc); // Update the document fetchedDoc.value = Math.random(); const updatedResponse = await db.put(fetchedDoc); console.log('Document updated:', updatedResponse); // Delete the document const deleteResponse = await db.remove(fetchedDoc); console.log('Document deleted:', deleteResponse); // Get database info const info = await db.info(); console.log('Database info:', info); } catch (err) { console.error('Error:', err); } finally { // Clean up: destroy the database when done await db.destroy(); console.log('Database destroyed.'); } } runExample();

Debug

Known issues

breakingPouchDB 8.0.0 introduced significant breaking changes by embracing modern ES6+ JavaScript syntax, refactoring to native JS classes, and deprecating older internal packages. Code relying on previous internal structures or older Node.js runtimes might break.

fix

Ensure your Node.js environment supports ES6+ features. Update your code to align with PouchDB's updated API and internal structure. Review the PouchDB 8.0.0 changelog for specific deprecated methods or properties.

affects: >=8.0.0

breakingPouchDB 9.0.0 is a major release with 202 PRs merged. While specific breaking changes are not detailed in the excerpt, a major version bump always indicates potential API changes, behavior modifications, or removal of deprecated features that could break existing applications.

fix

Thoroughly review the PouchDB 9.0.0 changelog and migration guide on the official PouchDB website or GitHub releases page. Test your application extensively after upgrading.

affects: >=9.0.0

gotchaWhen using `pouchdb-node`, it's crucial to understand it's a Node.js-specific build. It relies on LevelDB for storage and explicitly *does not* include browser-specific adapters like IndexedDB or WebSQL. Attempting to use browser-specific configurations or adapters with `pouchdb-node` will fail.

fix

Ensure your environment is Node.js. If you need a universal build or browser functionality, use the full `pouchdb` package or a custom build with the desired adapters. Do not pass browser-specific adapter options (e.g., `adapter: 'indexeddb'`) to `pouchdb-node`.

affects: >=6.0.0

gotcha`pouchdb-node` bundles several common plugins (replication, HTTP, map/reduce) by default. While convenient, this means if you were previously manually including these, you might now have redundant code or encounter unexpected behavior if your manual inclusions differ from the bundled versions.

fix

For replication, HTTP, and map/reduce functionalities, rely on the versions bundled with `pouchdb-node`. Only manually include other plugins that are not part of the `pouchdb-node` preset.

affects: >=6.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pouchdb-node'

The package `pouchdb-node` has not been installed or is not correctly resolved by your module system.

fix

Run `npm install pouchdb-node` or `yarn add pouchdb-node` in your project directory. Ensure your Node.js module resolution paths are correctly configured if you're using a monorepo or custom setup.

TypeError: PouchDB is not a constructor

This typically occurs when trying to use PouchDB in a CommonJS environment (using `require`) but treating it as an ES module default export, or vice-versa, especially if a build tool is misconfigured.

fix

For CommonJS, use `const PouchDB = require('pouchdb-node');`. For ES Modules, use `import PouchDB from 'pouchdb-node';`. If you are transpiling, ensure your Babel/TypeScript configuration correctly handles module interop.

Error: Missing adapter for pouchdb

Although `pouchdb-node` ships with the LevelDB adapter, this error can occur if there's a problem with the underlying LevelDB installation or its dependencies (like `leveldown`).

fix

Verify that `leveldown` and `levelup` (dependencies of `pouchdb-adapter-leveldb`) are correctly installed and compiled for your system. Reinstall `pouchdb-node` or `leveldown` to resolve potential native module compilation issues. Check Node.js version compatibility with LevelDB.

Upgrade

Version history

9.0.0latest on npm

Audit

Dependencies

pouchdb-adapter-leveldbrequiredThis package is the core storage adapter for Node.js, providing LevelDB functionality.

pouchdb-corerequiredProvides the foundational PouchDB API and database logic.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/pouchdb/pouchdb ↗

packagehttps://www.npmjs.com/package/pouchdb-node ↗

homepagehttps://pouchdb.com ↗