{"id":16496,"library":"pouchdb-adapter-http","title":"PouchDB HTTP Adapter","description":"pouchdb-adapter-http is a PouchDB plugin that enables the core PouchDB library to use HTTP as its data store, allowing it to seamlessly communicate and synchronize with remote CouchDB or CouchDB-like databases. This adapter is crucial for applications requiring offline-first capabilities combined with cloud synchronization. Currently stable at version 9.0.0, PouchDB maintains a consistent release cadence with frequent patch updates and less frequent major/minor versions. Key differentiators include its ability to abstract away the complexities of HTTP requests and responses, providing a familiar PouchDB API for remote data operations, and its design for use in both Node.js and browser environments, making it a versatile component within the PouchDB ecosystem.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/pouchdb/pouchdb","tags":["javascript"],"install":[{"cmd":"npm install pouchdb-adapter-http","lang":"bash","label":"npm"},{"cmd":"yarn add pouchdb-adapter-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add pouchdb-adapter-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an adapter for PouchDB, requiring the core PouchDB library to function via its plugin system.","package":"pouchdb","optional":false}],"imports":[{"note":"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.","wrong":"const PouchDB = require('pouchdb');","symbol":"PouchDB","correct":"import PouchDB from 'pouchdb';"},{"note":"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.","wrong":"const HttpPouch = require('pouchdb-adapter-http');","symbol":"HttpPouch","correct":"import HttpPouch from 'pouchdb-adapter-http';"},{"note":"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.","wrong":"const PouchDB = require('pouchdb');\nrequire('pouchdb-adapter-http'); // Adapter is not registered","symbol":"PouchDB.plugin","correct":"import PouchDB from 'pouchdb';\nimport HttpPouch from 'pouchdb-adapter-http';\nPouchDB.plugin(HttpPouch);"}],"quickstart":{"code":"import PouchDB from 'pouchdb';\nimport HttpPouch from 'pouchdb-adapter-http';\n\nPouchDB.plugin(HttpPouch);\n\n// Create a PouchDB instance that connects to a remote CouchDB via HTTP\nconst remoteDbUrl = process.env.COUCHDB_URL ?? 'http://127.0.0.1:5984/mydb';\nconst db = new PouchDB(remoteDbUrl);\n\nasync function runExample() {\n  try {\n    // Add a document\n    const doc = {\n      _id: 'mydoc-1',\n      title: 'Hello PouchDB HTTP',\n      description: 'This document is stored remotely.'\n    };\n    const response = await db.put(doc);\n    console.log('Document added:', response);\n\n    // Get the document\n    const fetchedDoc = await db.get('mydoc-1');\n    console.log('Document fetched:', fetchedDoc);\n\n    // You can also listen to changes, replicate, etc.\n    console.log(`PouchDB adapter in use: ${db.adapter}`);\n\n  } catch (err) {\n    console.error('Error:', err);\n  }\n}\n\nrunExample();","lang":"typescript","description":"This quickstart demonstrates how to import and register the HTTP adapter, then connect to a remote CouchDB instance, add a document, and retrieve it."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure `PouchDB.plugin(HttpPouch);` is called once in your application's bootstrap before any `new PouchDB('http://...')` calls are made.","message":"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.","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":"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.","cause":"The `pouchdb-adapter-http` plugin was not registered with the main PouchDB instance before being used.","error":"Error: Adapter 'http' is not installed."},{"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.","cause":"The remote CouchDB server is not configured to allow cross-origin requests from the origin where your PouchDB client application is running.","error":"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."}],"ecosystem":"npm"}