Skip to content
React/Preact Hooks for Typesaurus, type-safe Firestore ODM
TypeScript JavaScript Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Hello, cruel world! Jan 13, 2020
scripts Rework approach to universal React/Preact package Jan 15, 2020
src Fix the Preact package Jan 27, 2020
test Hello, cruel world! Jan 13, 2020
.clocignore Hello, cruel world! Jan 13, 2020
.gitignore Hello, cruel world! Jan 13, 2020
.prettierrc Hello, cruel world! Jan 13, 2020
.travis.yml Hello, cruel world! Jan 13, 2020
CHANGELOG.md
CONTRIBUTING.md Hello, cruel world! Jan 13, 2020
Makefile Rework approach to universal React/Preact package Jan 15, 2020
README.md Add documentation to README Jan 27, 2020
babel.config.js Hello, cruel world! Jan 13, 2020
karma.conf.js Hello, cruel world! Jan 13, 2020
package.json Fix the Preact package Jan 27, 2020
tsconfig.json Rework approach to universal React/Preact package Jan 15, 2020
yarn.lock Add useInfiniteQuery and useInfiniteScroll Jan 27, 2020

README.md

🦕 Reactopod

React Hooks for Typesaurus, type-safe Firestore ODM.


🔥🔥🔥 The project is sponsored by Backup Fire, backup service for Firebase 🔥🔥🔥

Installation

The library is available as an npm package. To install Reactopod run:

# React:
npm install reactopod --save
# Or using Yarn:
yarn add reactopod

# Preact:
npm install preactopod --save
# Or using Yarn:
yarn add preactopod

Note that Reactopod has Typesaurus listed as a peer dependency which also requires firebase package to work in the web environment. The latter isn't listed in dependencies, so make sure you did install both. For more info about Typesaurus dependencies, refer to its Installation section of README. Also, if you have to have react or preact installed for reactopod and preactopod respectively.

Get started

Initialization

To start working with Reactopod, initialize Firebase normally:

import * as firebase from 'firebase/app'
import 'firebase/firestore'

firebase.initializeApp({
  // Project configuration
})

See Firebase docs for more info.

Getting a single document

Use useGet hook to fetch document with the given id.

import { createElement } from 'react'
import { useGet } from 'reactopod'
import { collection } from 'typesaurus'

type User = { name: string }
const users = collection<User>('users')

function Component({ userId }: { userId: string }) {
  const user = useGet(users, userId)
  return user ? <div>Hello, {user.data.name}</div> : <div>Loading...</div>
}

Use useOnGet hook to subscribe to a document with the given id. When the document changes you'll receive the new data automatically.

import { createElement } from 'react'
import { useOnGet } from 'reactopod'
import { collection } from 'typesaurus'

type User = { name: string }
const users = collection<User>('users')

function Component({ userId }: { userId: string }) {
  const user = useGet(users, userId)
  return user ? <div>Hello, {user.data.name}</div> : <div>Loading...</div>
}

Getting all documents from a collection

Use useAll hook to fetch all documents from a collection.

import { createElement } from 'react'
import { useAll } from 'reactopod'
import { collection } from 'typesaurus'

type User = { name: string }
const users = collection<User>('users')

function Component() {
  const allUsers = useAll(users)
  return allUsers ? (
    <ul>
      {allUsers.map(user => (
        <li>{user.data.name}</li>
      ))}
    </ul>
  ) : (
    <div>Loading...</div>
  )
}

Use useOnAll hook to subscribe to all documents within a collection. When a document in the collection changes you'll receive the new data.

import { createElement } from 'react'
import { useOnAll } from 'reactopod'
import { collection } from 'typesaurus'

type User = { name: string }
const users = collection<User>('users')

function Component() {
  const allUsers = useOnAll(users)
  return allUsers ? (
    <ul>
      {allUsers.map(user => (
        <li>{user.data.name}</li>
      ))}
    </ul>
  ) : (
    <div>Loading...</div>
  )
}

Querying documents from a collection

Use useQuery hook to query documents from a collection using using query objects.

import { createElement } from 'react'
import { useQuery } from 'reactopod'
import { collection, where } from 'typesaurus'

type Game = { title: string; platform: 'switch' | 'xbox' | 'ps' | 'pc' }
const games = collection<Game>('games')

function Component() {
  const switchGames = useQuery(games, [where('platform', '==', 'switch')])
  return switchGames ? (
    <ul>
      {switchGames.map(game => (
        <li>{game.data.title}</li>
      ))}
    </ul>
  ) : (
    <div>Loading...</div>
  )
}

Use useOnQuery hook to subscribe to a query results. When the result changes you'll receive the new data.

import { createElement } from 'react'
import { useOnQuery } from 'reactopod'
import { collection, where } from 'typesaurus'

type Game = { title: string; platform: 'switch' | 'xbox' | 'ps' | 'pc' }
const games = collection<Game>('games')

function Component() {
  const switchGames = useOnQuery(games, [where('platform', '==', 'switch')])
  return switchGames ? (
    <ul>
      {switchGames.map(game => (
        <li>{game.data.title}</li>
      ))}
    </ul>
  ) : (
    <div>Loading...</div>
  )
}

See Typesaurus documentation for more info about the query objects:

  • order - Creates order query object with given field, ordering method and pagination cursors.
  • limit - Creates a limit query object. It's used to paginate queries.
  • where - Creates where query with array-contains filter operation.

Pagination helpers:

  • endAt - Ends the query results on the given value.
  • endBefore - Ends the query results before the given value.
  • startAfter - Start the query results after the given value.
  • startAt - Start the query results on the given value.

Querying documents with pagination

Use useInfiniteQuery to query documents with pagination.

The function returns an array where the first element is the result and the second is loadMore. loadMore is undefined when the result is loading. loadMore is null when there're no more data to load. Otherwise loadMore is a function that triggers loading of the next page.

import { createElement } from 'react'
import { useInfiniteQuery } from 'reactopod'
import { collection, where } from 'typesaurus'

type Game = {
  title: string
  platform: 'switch' | 'xbox' | 'ps' | 'pc'
  publishedAt: Date
}
const games = collection<Game>('games')

function Component() {
  const [switchGames, loadMore] = useInfiniteQuery(
    games,
    [where('platform', '==', 'switch')],
    { field: 'publishedAt', method: 'desc', limit: 10 }
  )

  return switchGames ? (
    <div>
      <ul>
        {switchGames.map(game => (
          <li>{game.data.title}</li>
        ))}
      </ul>

      {loadMore === undefined ? (
        <div>Loading more...</div>
      ) : loadMore === null ? null : (
        <button onClick={loadMore}>Load more</button>
      )}
    </div>
  ) : (
    <div>Loading...</div>
  )
}

Combine useInfiniteQuery with useInfiniteScroll to implement the infinite scroll.

useInfiniteScroll accepts two arguments. The first is the scroll threshold. If you pass 1.5, then more results will load when the scroll position is more than full height minus 1.5 x screen height. The second argument is loadMore function returned from useInfiniteQuery.

import { createElement } from 'react'
import { useInfiniteQuery, useInfiniteScroll } from 'reactopod'
import { collection, where } from 'typesaurus'

type Game = {
  title: string
  platform: 'switch' | 'xbox' | 'ps' | 'pc'
  publishedAt: Date
}
const games = collection<Game>('games')

function Component() {
  const [switchGames, loadMore] = useInfiniteQuery(
    games,
    [where('platform', '==', 'switch')],
    { field: 'publishedAt', method: 'desc', limit: 10 }
  )
  useInfiniteScroll(1.5, loadMore)
  return switchGames ? (
    <ul>
      {switchGames.map(game => (
        <li>{game.data.title}</li>
      ))}
    </ul>
  ) : (
    <div>Loading...</div>
  )
}

Changelog

See the changelog.

License

MIT © Sasha Koss

You can’t perform that action at this time.