usePouchDB

Overview

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

The goal of usePouchDB 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 usePouchDB. 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

usePouchDB 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 usePouchDB

usePouchDB 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 'use-pouchdb'

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 'use-pouchdb'

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>
  )
}

Changelog

usePouchDB follows semantic versioning. To see a changelog with all usePouchDB 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.

Lexty/use-pouchdb