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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PouchDBReplicator
✓ import PouchDB from 'pouchdb';
import PouchDBReplicator from 'pouchdb-replicator';
✗ const PouchDB = require('pouchdb');
const PouchDBReplicator = require('pouchdb-replicator'); // CommonJS for older Node
The primary way to use this plugin is to import its default export and register it with `PouchDB.plugin()`. Ensure `pouchdb` itself is imported correctly first. While CommonJS is shown as 'wrong' for modern contexts, it's still prevalent in older Node.js projects, but ESM is preferred for PouchDB since v7.
PouchDB.plugin
✓ PouchDB.plugin(PouchDBReplicator);
✗ new PouchDBReplicator();
// or just importing without registering
PouchDB plugins must be registered with the global `PouchDB` object using the `.plugin()` method for their functionality to become available on database instances.
PouchDB
✓ import PouchDB from 'pouchdb';
✗ import { PouchDB } from 'pouchdb';
// or not importing it at all
`PouchDB` is typically imported as a default export, even though it exposes many named utilities. Forgetting to import it, or importing it incorrectly, will prevent plugin registration.
This quickstart demonstrates how to register `pouchdb-replicator` as a plugin and then initiate a continuous replication job by creating a document in the special `_replicator` database. This simulates CouchDB's declarative replication management.
import PouchDB from 'pouchdb';
import PouchDBReplicator from 'pouchdb-replicator';
// Register the PouchDB Replicator plugin
PouchDB.plugin(PouchDBReplicator);
async function setupPersistentReplication() {
// Initialize a local PouchDB database
const localDb = new PouchDB('my_local_db');
// Define a remote PouchDB/CouchDB instance URL
const remoteDbUrl = 'http://localhost:5984/my_remote_db'; // Ensure CouchDB is running or this is a valid PouchDB instance
// The special _replicator database to manage replication jobs
const replicatorDb = new PouchDB('_replicator');
try {
// Create a continuous replication job by posting a document to _replicator
// This will instruct PouchDB-Replicator to start and manage the replication.
const replicationJob = {
_id: 'my-first-continuous-sync',
source: localDb.name, // Source database: 'my_local_db'
target: remoteDbUrl, // Target database: 'http://localhost:5984/my_remote_db'
continuous: true, // Keep replication running continuously
live: true, // Also track future changes (often implied by continuous)
retry: true, // Automatically retry on failure
// For authenticated replication to a remote CouchDB:
// auth: {
// username: process.env.COUCHDB_USERNAME ?? 'admin',
// password: process.env.COUCHDB_PASSWORD ?? 'password'
// }
};
const response = await replicatorDb.put(replicationJob);
console.log('Replication job started successfully:', response);
// To stop or update the replication, you would modify or delete this document from _replicator
// e.g., await replicatorDb.remove(response.id, response.rev);
} catch (error: any) {
console.error('Failed to set up replication job:', error);
// Handle common errors like network issues, authentication failures, etc.
}
}
setupPersistentReplication();
Debug
Known issues
breakingVersion 4.0.0 was the first release built from a complete monorepo, changing internal structures and dependencies. It also addressed a security issue. While the impact on direct API usage for `pouchdb-replicator` itself might be minimal, users upgrading from pre-4.0.0 versions should be aware of potential broader ecosystem changes within `pouchdb-server`.fixReview the full `pouchdb-server` 4.0.0 changelog for details on monorepo migration and dependency impacts. Ensure all related PouchDB packages are compatible with this new structure.
affects: >=4.0.0 <4.0.1
breakingVersion 2.0.0 introduced breaking changes that correspond to `express-pouchdb` 2.0.0, specifically impacting database name encoding for adapters that store files. If database names contained '/' characters, existing databases might not be found. Additionally, version 2.0.0 onward uses prefixed replication fields (`_replication_state` instead of `replication_state`).fixFor affected database names, migration may involve renaming database files or adjusting how names are handled. Ensure PouchDB is updated to a version where issue 2442 is solved to support the prefixed replication fields.
affects: >=2.0.0 <3.0.0
gotchaA potential `EventEmitter` memory leak issue was fixed in version 4.1.0 (#233). Applications with many active replications or frequent replication job changes might have experienced memory consumption growth over time in earlier versions.fixUpgrade to `pouchdb-replicator@4.1.0` or later to benefit from the memory leak fix.
affects: >=2.0.0 <4.1.0
gotchaVersion 4.2.0 fixed an issue where `.info` errors were being swallowed, leading to silent failures or missed diagnostic information during replication.fixUpgrade to `pouchdb-replicator@4.2.0` or later to ensure proper error reporting for `.info` calls.
affects: >=4.0.0 <4.2.0
breakingPouchDB (and by extension its plugins like `pouchdb-replicator`) has evolved towards ESM. While older versions might support CommonJS, modern PouchDB usage (especially with recent versions like v7+) strongly encourages ESM for better compatibility and tree-shaking.fixAdopt ES Module syntax (`import ... from '...'`) throughout your project. If bundling for older environments, ensure your build setup correctly transpiles ESM to CJS.
affects: >=7.0.0 (PouchDB)
deprecatedThe broader PouchDB ecosystem has seen significant shifts, with some perspectives considering PouchDB legacy for high-performance use cases due to revision handling overhead and bundle size. While `pouchdb-replicator` remains functional, consider the long-term architectural implications if performance or strict modern database standards are critical.fixFor new projects with extreme performance requirements or specific modern sync patterns (e.g., WebRTC, GraphQL), evaluate alternative RxDB storage engines. For existing PouchDB applications, continue using `pouchdb-replicator` but be mindful of its inherent characteristics.
affects: >=4.0.0
Errors
Common errors & fixes
TypeError: PouchDB.plugin is not a function
The PouchDB library was either not imported, imported incorrectly (e.g., named import instead of default), or the `PouchDB.plugin()` method was called before the PouchDB object was properly initialized.
fixEnsure `import PouchDB from 'pouchdb';` is at the top of your file and that `PouchDB.plugin(PouchDBReplicator);` is called after PouchDB is ready.
Error: Database not found or permission denied
This error typically occurs during replication if the source or target database URL is incorrect, the database does not exist, or there are insufficient authentication credentials/permissions to access the remote database.
fixDouble-check the `source` and `target` URLs/names in your `_replicator` document. If replicating to a remote CouchDB, ensure `auth` options (username, password) are correctly provided in the replication document, or the user has appropriate roles set up.
Error: Document update conflict
When updating a replication document in the `_replicator` database, you must provide the correct `_rev` of the existing document. If the `_rev` is missing or stale, a conflict will occur.
fixBefore updating a replication document, fetch its current `_rev` (e.g., via `replicatorDb.get(id)`), then include that `_rev` in your `put()` or `post()` call. Alternatively, use a PouchDB upsert plugin if available.
TypeError: Cannot read properties of undefined (reading 'name') on 'source' or 'target'
If `source` or `target` are PouchDB database objects instead of names/URLs, this error suggests that the PouchDB instance itself (e.g., `localDb` in the quickstart) was not properly initialized or is `undefined` when its `.name` property is accessed.
fixEnsure that `new PouchDB('db_name')` calls are awaited or handled as promises, and that the resulting PouchDB objects are valid before being used in the replication document. Audit
Dependencies
pouchdbrequiredThis package is a PouchDB plugin and extends the core PouchDB object.