PouchDB HTTP Adapter

Common errors

• Error: Adapter 'http' is not installed.

  cause The `pouchdb-adapter-http` plugin was not registered with the main PouchDB instance before being used.
  fix Add `import HttpPouch from 'pouchdb-adapter-http'; PouchDB.plugin(HttpPouch);` to your application's initialization code. Ensure it runs before creating any PouchDB instances that use the 'http' or 'https' adapter.

• Access to fetch at 'http://127.0.0.1:5984/mydb' from origin 'http://localhost:8080' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause The remote CouchDB server is not configured to allow cross-origin requests from the origin where your PouchDB client application is running.
  fix Configure the CouchDB server to enable CORS. This typically involves modifying `local.ini` or `default.ini` to set `[httpd]` bind address and `[cors]` options (origins, methods, headers). For development, you might use a proxy.

Warnings

• breaking PouchDB 9.0.0 is a major release with 202 PRs merged. While specific changes for 'pouchdb-adapter-http' are not detailed in the excerpt, major version bumps typically introduce breaking changes across the ecosystem. Users should consult the full PouchDB changelog before upgrading from 8.x.
  Fix: Review the official PouchDB 9.0.0 release notes and changelog carefully for migration instructions. Test thoroughly in a staging environment before deploying to production.
• breaking PouchDB 8.0.0 initiated a transition to modern ES6+ JavaScript syntax, including refactors to use native JS classes instead of prototypes. While 'pouchdb-adapter-http' primarily acts as a plugin, direct interaction with its internal structure or extending it with older patterns may be affected.
  Fix: Ensure your project's JavaScript environment and build tools are configured for ES6+. If you have custom code interacting deeply with PouchDB's internals, review it for compatibility with modern class-based structures.
• gotcha When connecting a browser-based PouchDB client to a remote CouchDB server, Cross-Origin Resource Sharing (CORS) policies can block requests. This is a common security feature that prevents unauthorized cross-origin data access.
  Fix: Configure your CouchDB server (or reverse proxy) to include appropriate CORS headers (e.g., `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`). Use a tool like `cors-anywhere` for development, but implement proper server-side CORS for production. Refer to CouchDB documentation for CORS setup.
• gotcha Failing to register the `pouchdb-adapter-http` plugin with `PouchDB.plugin()` before attempting to create a database instance using the 'http' or 'https' adapter will result in an error indicating the adapter is not found.
  Fix: Always ensure `PouchDB.plugin(HttpPouch);` is called once in your application's bootstrap before any `new PouchDB('http://...')` calls are made.

Install

• npm install pouchdb-adapter-http npm
• yarn add pouchdb-adapter-http yarn
• pnpm add pouchdb-adapter-http pnpm

Imports

• PouchDB
  wrong:

  const PouchDB = require('pouchdb');

  correct:

  import PouchDB from 'pouchdb';

  ESM is the preferred import style for PouchDB 8.x and above. While `require` works in CJS contexts, use `import` for modern projects, especially with bundlers or in 'type: module' environments.
• HttpPouch
  wrong:

  const HttpPouch = require('pouchdb-adapter-http');

  correct:

  import HttpPouch from 'pouchdb-adapter-http';

  This adapter package is 'type: module' since PouchDB v8.0.0, so ESM `import` is the primary way. Legacy `require` may work in some setups but is discouraged in new code.
• PouchDB.plugin
  wrong:

  const PouchDB = require('pouchdb');
  require('pouchdb-adapter-http'); // Adapter is not registered

  correct:

  import PouchDB from 'pouchdb';
  import HttpPouch from 'pouchdb-adapter-http';
  PouchDB.plugin(HttpPouch);

  The adapter must be explicitly registered with `PouchDB.plugin()` to make the 'http' or 'https' adapter available. This is crucial whether using ESM or CJS imports.

Quickstart

This quickstart demonstrates how to import and register the HTTP adapter, then connect to a remote CouchDB instance, add a document, and retrieve it.

import PouchDB from 'pouchdb';
import HttpPouch from 'pouchdb-adapter-http';

PouchDB.plugin(HttpPouch);

// Create a PouchDB instance that connects to a remote CouchDB via HTTP
const remoteDbUrl = process.env.COUCHDB_URL ?? 'http://127.0.0.1:5984/mydb';
const db = new PouchDB(remoteDbUrl);

async function runExample() {
  try {
    // Add a document
    const doc = {
      _id: 'mydoc-1',
      title: 'Hello PouchDB HTTP',
      description: 'This document is stored remotely.'
    };
    const response = await db.put(doc);
    console.log('Document added:', response);

    // Get the document
    const fetchedDoc = await db.get('mydoc-1');
    console.log('Document fetched:', fetchedDoc);

    // You can also listen to changes, replicate, etc.
    console.log(`PouchDB adapter in use: ${db.adapter}`);

  } catch (err) {
    console.error('Error:', err);
  }
}

runExample();