{"id":16662,"library":"pouchdb-users","title":"PouchDB Users Database Plugin","description":"pouchdb-users is a PouchDB plugin designed to simulate the behavior of CouchDB's `_users` database. It handles password hashing (using PBKDF2) and ensures user document formats adhere to CouchDB's specifications. This allows developers to use any PouchDB adapter, including in-memory or LevelDB-based local storage, for persisting user accounts, thereby decoupling user management from a live CouchDB instance for basic operations. The current stable version is 1.0.6, released in June 2017. The package has seen no updates since then, indicating it is no longer actively maintained. Its key differentiator is enabling offline-first user account management within PouchDB environments without requiring a constant connection to a CouchDB `_users` database for operations like user creation and retrieval. It explicitly does *not* implement access control, focusing solely on document format and password security for user records.","status":"abandoned","version":"1.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/hoodiehq/pouchdb-users","tags":["javascript","couchdb","pouchdb","plugin","users","authentication"],"install":[{"cmd":"npm install pouchdb-users","lang":"bash","label":"npm"},{"cmd":"yarn add pouchdb-users","lang":"bash","label":"yarn"},{"cmd":"pnpm add pouchdb-users","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for PouchDB and requires a PouchDB instance to operate.","package":"pouchdb","optional":false},{"reason":"Used for password hashing, mirroring CouchDB's password security mechanisms.","package":"pbkdf2","optional":false},{"reason":"Supports internal PouchDB plugin mechanisms, likely for view-related operations on user documents.","package":"pouchdb-mapreduce-utils","optional":false}],"imports":[{"note":"This package primarily supports CommonJS `require()` patterns. Modern PouchDB versions might have ESM support, but this plugin is designed for older CommonJS PouchDB environments.","wrong":"import PouchDB from 'pouchdb'","symbol":"PouchDB","correct":"const PouchDB = require('pouchdb')"},{"note":"Import the plugin module using CommonJS `require()` for compatibility.","wrong":"import PouchDBUsers from 'pouchdb-users'","symbol":"pouchdb-users","correct":"const PouchDBUsers = require('pouchdb-users')"},{"note":"PouchDB plugins are installed on the `PouchDB` constructor itself, not on an individual database instance.","wrong":"db.plugin(require('pouchdb-users'))","symbol":"plugin installation","correct":"PouchDB.plugin(require('pouchdb-users'))"}],"quickstart":{"code":"const PouchDB = require('pouchdb')\nPouchDB.plugin(require('pouchdb-users'))\nconst memdown = require('memdown') // For an in-memory database example\n\nasync function setupUsersDatabase() {\n  const db = new PouchDB('my-users', { db: memdown })\n\n  console.log('Installing users behavior...')\n  await db.installUsersBehavior()\n  console.log('Users behavior installed.')\n\n  console.log('Creating a new user...')\n  const newUserDoc = {\n    _id: 'org.couchdb.user:testuser',\n    type: 'user',\n    name: 'testuser',\n    password: 'supersecretpassword123'\n  }\n  const response = await db.put(newUserDoc)\n  console.log('User created/updated:', response)\n\n  console.log('Fetching the user document to see hashed password...')\n  const userDoc = await db.get('org.couchdb.user:testuser')\n  console.log('Retrieved user document:', userDoc)\n\n  // Example against a remote CouchDB _users database (requires admin credentials)\n  // const remoteDb = new PouchDB('http://localhost:5984/_users', {\n  //   auth: {\n  //     username: process.env.COUCHDB_ADMIN_USERNAME ?? 'admin',\n  //     password: process.env.COUCHDB_ADMIN_PASSWORD ?? 'adminpassword'\n  //   }\n  // })\n  // await remoteDb.installUsersBehavior()\n  // console.log('Remote users behavior installed.')\n  // const remoteResponse = await remoteDb.put({\n  //   _id: 'org.couchdb.user:remoteuser',\n  //   type: 'user',\n  //   name: 'remoteuser',\n  //   password: 'anothersecretpassword'\n  // })\n  // console.log('Remote user created:', remoteResponse)\n}\n\nsetupUsersDatabase().catch(console.error)\n","lang":"javascript","description":"Demonstrates how to install the pouchdb-users plugin and create a new user document, showing how the password gets hashed and stored in a CouchDB-compatible format within a local PouchDB instance."},"warnings":[{"fix":"Always build your own access control layer or use a separate authentication/authorization system alongside `pouchdb-users`.","message":"pouchdb-users explicitly does NOT implement any access restrictions or user context. It solely handles password hashing and document formatting for CouchDB's `_users` database. You will need to implement your own authorization logic on top of this plugin.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider migrating to more actively maintained PouchDB authentication solutions or developing custom logic for user management if long-term support is critical. Evaluate the risks of using unmaintained software carefully.","message":"This package is no longer actively maintained; the last release was in June 2017. This may lead to compatibility issues with newer Node.js versions, updated PouchDB APIs, or potential security vulnerabilities due to unaddressed bugs or outdated dependencies (e.g., in `pbkdf2`).","severity":"deprecated","affected_versions":">=1.0.6"},{"fix":"Ensure your project's module resolution for PouchDB and its plugins is configured for CommonJS, or use older Node.js versions if encountering module loading issues. Consider using a bundler like Webpack or Rollup to handle compatibility.","message":"The plugin is designed for PouchDB environments that primarily use CommonJS `require()`. While PouchDB itself has evolved, this plugin might not be directly compatible with pure ESM environments without transpilation or specific build configurations.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `const PouchDB = require('pouchdb')` is called before attempting to install the plugin, and that `PouchDB.plugin()` is used, not `db.plugin()`.","cause":"PouchDB was not loaded or aliased correctly, or the plugin was attempted to be installed on a database instance instead of the PouchDB constructor.","error":"TypeError: PouchDB.plugin is not a function"},{"fix":"Verify that `PouchDB.plugin(require('pouchdb-users'))` is called prior to `new PouchDB()` or `db = new PouchDB()`.","cause":"The `pouchdb-users` plugin was not successfully installed on the PouchDB constructor before initializing the database instance.","error":"TypeError: db.installUsersBehavior is not a function"},{"fix":"When updating an existing user, retrieve the document first to get its `_rev`, then include `_rev` in the updated document. Alternatively, handle the conflict in your `catch` block.","cause":"Attempted to `put` a user document with an `_id` that already exists without specifying the `_rev` property of the existing document, or without handling the conflict programmatically.","error":"Error: Document update conflict"}],"ecosystem":"npm"}