@aegu/react-pouchdb-hooks

Note: This is a fork of the original use-pouchdb library by Christopher Astfalk. This fork includes performance improvements, enhanced features, and continued maintenance. All credit for the original design and implementation goes to the original author.

React Hooks for PouchDB.

Overview

reactPouchDBHooks is a collection of React Hooks to access data in a PouchDB database from React components.

The goal of reactPouchDBHooks is to ease the use of PouchDB with React. Enabling developers to create offline first apps.

Quick-start

You can find the Getting Started docs here (or on GitHub).

These docs walk you through setting up PouchDB and reactPouchDBHooks. They give you also a quick introduction to PouchDB and Apache CouchDB. But PouchDB's Guides are recommended to learn PouchDB.

You can find a introduction to React here.

If you know what you're doing and only want to quick start, read on...

Installation

reactPouchDBHooks requires React 16.8.3 or later.

npm install use-pouchdb
# or
yarn add use-pouchdb

You'll also need to install PouchDB. There is also a special browser version:

npm install pouchdb-browser
# or
yarn add pouchdb-browser

To use the useView hook pouchdb-mapreduce must be installed and setup. If you use the pouchdb or pouchdb-browser packages, it is already setup.

npm install pouchdb-mapreduce
# or
yarn add pouchdb-mapreduce

For using the useFind hook pouchdb-find must be installed and setup.

npm install pouchdb-find
# or
yarn add pouchdb-find

Bind reactPouchDBHooks

reactPouchDBHooks exports a <Provider /> to make one or multiple PouchDB databases available to its components sub-tree.

import React from 'react'
import ReactDOM from 'react-dom'
import PouchDB from 'pouchdb-browser'

import { Provider } from '@aegu/react-pouchdb-hooks'

import App from './App'

const db = new PouchDB('local')

ReactDOM.render(
  <Provider pouchdb={db}>
    <App />
  </Provider>,
  document.getElementById('root'),
)

Hooks

All hooks are listed here.

• usePouch - Access the database provided by <Provider />.
• useDoc - Access a single document and subscribe to its changes. The hook version of db.get.
• useAllDocs - Load multiple documents and subscribe to their changes. Or a range of docs by their ids. The hook version of db.allDocs.
• useFind - Access a mango index and subscribe to it. Optionally create the index, if it doesn't exist. The hook version of db.createIndex and db.find combined.
• useView - Access a view and subscribe to its changes. The hook version of db.query.

Example

Load a single document and display it. useDoc is the hook version of db.get, but it also subscribes to updates of that document and automatically loads the new version.

import React from 'react'
import { useDoc } from '@aegu/react-pouchdb-hooks'

export default function Post({ postId }) {
  const { doc, loading, error } = useDoc(postId)

  if (error && !loading) {
    return <div>something went wrong: {error.name}</div>
  }

  if (doc == null && loading) {
    return null
  }

  return (
    <article>
      <div>
        <h3>{doc.author}</h3>
        <p>{doc.text}</p>
      </div>
    </article>
  )
}

Populate Referenced Documents

reactPouchDBHooks supports automatic population of referenced documents, similar to SQL JOINs. Use dot notation for nested field references:

import React from 'react'
import { useDoc } from '@aegu/react-pouchdb-hooks'

export default function OrderDetails({ orderId }) {
  const {
    doc: order,
    loading,
    error,
  } = useDoc(orderId, {
    populate: {
      // Flat references
      siteId: { as: 'site' },
      customerId: { as: 'customer' },
      // Nested references - use dot notation
      'material_info.cultivar_id': { as: 'material_info.cultivar' },
      'shipping.vendor_id': { as: 'shipping.vendor' },
    },
  })

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.name}</div>

  return (
    <article>
      <h1>Order for {order.customer?.name}</h1>
      <p>Site: {order.site?.name}</p>

      <h3>Material</h3>
      <p>Cultivar: {order.material_info?.cultivar?.name}</p>
      <p>Quantity: {order.material_info?.quantity}</p>

      <h3>Shipping</h3>
      <p>Vendor: {order.shipping?.vendor?.name}</p>
    </article>
  )
}

Query Key Pattern

All query hooks (useFind, useAllDocs, useView) support query keys for stable query identification and optimal performance, similar to TanStack Query and SWR:

// TanStack Query style
const { docs } = useFind({
  selector: { type: 'Product' },
  queryKey: ['products', categoryId, filters], // Stable cache key
})

// Auto-optimized (backward compatible)
const { docs } = useFind({
  selector: { type: 'Product' },
  // queryKey auto-generated for optimal performance
})

Query keys prevent unnecessary database queries when components re-render with recreated objects, providing significant performance improvements.

Learn more about Query Keys →

Changelog

reactPouchDBHooks follows semantic versioning. To see a changelog with all reactPouchDBHooks releases, check out the Github releases page.

Contributing

Contributions in all forms are welcomed. ♡

If you have questions, Contributing.md might answer your questions.

To create a welcoming project to all, this project uses and enforces a Code of Conduct.