Registry / database / pouchdb-adapter-http

pouchdb-adapter-http

library9.0.0jsnpmunverified

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.

database http-networking web-framework

npm install pouchdb-adapter-http

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POUCHDB-ADAPTER-HT

pouchdb-adapter-http

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';

✗ const PouchDB = require('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

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

✗ const HttpPouch = require('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

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

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

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.

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();

Debug

Known issues

breakingPouchDB 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.

affects: >=9.0.0

breakingPouchDB 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.

affects: >=8.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaFailing 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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Adapter 'http' is not installed.

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.

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.

Upgrade

Version history

9.0.0latest on npm

Audit

Dependencies

pouchdbrequiredThis package is an adapter for PouchDB, requiring the core PouchDB library to function via its plugin system.

Agent activity

7 hits · last 30 days

node

Resources

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

packagehttps://www.npmjs.com/package/pouchdb-adapter-http ↗

homepagehttps://pouchdb.com ↗