@fireproof/database NPM

Fireproof is the quickest way to add live data to your React or other front-end app. Install anywhere JavaScript goes:

npm install @fireproof/core

or via <script src="..."> tag referencing fireproof.iife.js for plain old HTML apps. (CDN link coming soon.)

If you are using React, jump to the useFireproof README, which is the preferred way to consume the database in client-side React code, or for a longer explanation, try the step-by-step React tutorial.

Vanilla JS Example

Fireproof uses end-to-end encryption, immutable data, and distributed protocols so your app is easy to start and seriously scales. Add a few lines to your front-end pages and you'll be developing with a live database with no other setup:

import { database, index } from '@fireproof/core'

const db = database('my-app-name')
const byAge = index(db, 'age')

const onChange(async () => {
  const { rows } = await byAge.query({ range: [40, 52] })
  console.log(rows)
})
db.subscribe(onChange)
onChange()

async function doChange(name, age)  {
  await db.put({ name, age })
}
/// ... meanwhile ... 
onClick = () => doChange(name, age)

Fireproof can be embedded in any page or app, and connect with any cloud (coming soon) via REST, S3, and web3.storage support. If you have particular storage needs, reach out and we can help you write a custom storage adapter.

Why choose Fireproof

Fireproof has a unique take on distributed data integrity, rooted in immutable data and cryptographically verifiable protocols (what plants crave). This allows you to add live data to your app without complex configuration or installation (it's just an npm module) and if you decide to connect to the cloud you can easily choose storage providers or connect to your own S3 bucket. End-to-end encryption allows you to manage keys separately from data, defining custom security policies, so you can get started today connect to any environment when you are ready.

Database Features

The core features of the database are available on any platform in a compact JavaScript package and a foundational cloud storage service.

JSON Documents - Encrypted changes are persisted locally and to any connected storage. Store any JSON object using a familiar document database API.
Live Query - Sort and filter any database with CouchDB-style map functions. The useFireproof React hook integrates so cleanly your code doesn't even have to import useState or useEffect, instead, useLiveQuery makes dynamic renders easy.
Realtime Updates - Subscribe to query changes in your application, so your UI updates automatically. This makes vanilla JS apps super easy to build -- the useFireproof React hook handles this so you won't need db.subscribe() there.
Cryptographic Proofs - Fireproof's Merkle clocks and hash trees are immutable and self-validating, making all query results into offline-capable data slices. Fireproof makes cryptographic proofs available for all of its operations, accelerating replication and making trustless index sharing possible. This makes it a great choice for building custom document approval workflows or other situations where provenance is important.

Learn more about the architecture behind Fireproof.

Use cases

Fireproof is optimized to make building React apps fast and fun, with reliable results. Suitable for mission-critical data workloads like LLM orchestration, supply-chain provenance, and field use of auditable data, Fireproof is also great for social media, collaborative world-building, and rapidly implementing executive decision support tools that can stand up to blockchain levels of scrutiny.

With Fireproof, you build first and connect it to your cloud of choice when you are ready, so there's nothing holding you back from adding it to your existing apps, or writing something new.

React Quick Start

One-line preview: in the context of a React component render, useLiveQuery will automatically refresh (even on changes by remote collaborators):

  const completedTodos = useLiveQuery('completed', { limit: 10 })

This is the README for the core database technology. The useFireproof hook documentation has a getting started guide. Don't forget to star 🌟 this repo on the way over.

AI Copilot Quick Start

Because Fireproof is designed to let you get started in the browser and connect to the cloud when you're ready, it's ideal for AI-assisted app development. If you are using GPT, Claude, or Bard, you can easily enable the AI to write React apps using Fireproof.

Working with an AI assistant is a great way to get started on projects or try out new frameworks. Paste this line of code into your prompt, along with a detailed description of the app to build, and your app will be running without ever requiring a cloud.

Fireproof/React/Usage: import { useFireproof } from '@fireproof/react'; function App() { const { useLiveQuery, useDocument, database } = useFireproof(); const result = useLiveQuery(doc => doc.word, { limit: 10 }); const [{ count }, saveCountDocument] = useDocument({_id: 'count', count: 0}); return (<><p>{count} changes</p><input type='text' onChange={() => saveCountDocument({count: count + 1})} onSubmit={e => database.put({word: e.target.value})} /><ul>{result.map(row => (<li key={row.id}>{row.key}</li>))}</ul></>)}

For example prompts and inspiration check out the illustrated version of this technique with links to saved chats that are ready to go.

API Usage

Encrypted Documents

A simple put, get and delete interface for keeping track of all your JSON documents. Once your data is in Fireproof you can access it from any app or website.

const { id } = await database.put({
    _id: 'three-thousand'
    name: 'André',
    age: 47
});

const doc = await database.get('three-thousand') 
// {
//    _id  : 'three-thousand'
//    name : 'André',
//    age  : 47
// }

Fireproof tracks all versions so undo is easy to write, and cryptographically verifiable snapshots of the database are as easy as web links.

Live Query

Fireproof provides a live query interface that allows you to subscribe to changes in your data. This means that your UI will automatically update whenever there is a change to your data. See the useFireproof React hooks documentation for the easiest way to use this feature.

Fireproof indexes are defined by custom JavaScript functions that you write, allowing you to easily index and search your data in the way that works best for your application. Easily handle data variety and schema drift by normalizing any data to the desired index. The index function defines the sort order. You can use the index to query for a range of values or to find exact matches. This baseline functionality is all you need to build many kinds of complex queries.

const byAge = index(database, "age")
const { rows } = await index.query({ range: [40, 52] })

By default you can specify your function as a string and Fireproof will interpret it as indexing that field on any documents. Read on for examples of how you can get more control when you want. The optional second argument to your map function allows you to specify both keys and values for the index:

const index = new Index(database, "namesByAge", function (doc, map) {
  map(doc.age, doc.name)
})
const { rows, ref } = await index.query({ range: [40, 52] })
// [ { key: 42, value: 'alice', id: 'a1s3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c' },
//   { key: 47, value: 'André', id: 'three-thousand' } ]

The same mechanism that powers the built-in indexes can all be used to connect secondary vector indexers or fulltext indexes to Fireproof. Follow this tutorial to connect a secondary index.

Realtime Updates

Subscribe to query changes in your application, so your UI updates automatically. Use the supplied React hooks, or simple function calls to be notified of relevant changes.

const unsubscribe = database.subscribe(changes) => {
  changes.forEach(change => {
    console.log(change)
  })
})

Return the unsubscribe function from useEffect and React will handle it for you. (In the code below, we use the arrow function's implicit return to connect the unsubscribe function to the useEffect hook. This prevents extra subscriptions from building up on each render.)

useEffect(() => database.subscribe((changes) => 
    changes.forEach(change => console.log(change))), [])

The React useLiveQuery hook automatically refreshes query results for you, but under the hood, it's just calling index.query() and calling setState() when the results change. You can use the same technique to build your live query UIs with any framework.

Cryptographic Proofs

Fireproof's Merkle clocks and hash trees are immutable and self-validating, and all query results are offline-capable data slices. Fireproof makes cryptographic proofs available for all of its operations, accelerating replication and making trustless index sharing possible. If you are making a "DocuSign for _", proofs make Fireproof the ideal verifiable document database for smart contracts and other applications where unique, verifiable, and trustworthy data is required. Proof chains provide performance benefits as well, by allowing recipients to skip costly I/O operations and instead cryptographically verify that changes contain all of the required context.

Coming Soon

The six-month roadmap for Fireproof includes these features to make it a complete offering for application data.

Cloud Storage

When you are ready to save your data to the cloud for sharing or backup:

import { connect } from '@fireproof/core'

const connection = await connect(db, 'my-account-email@example.com')

You can tie any app to your app developer storage account, or allow users to create personal storage accounts (at no cost to you).

Automatic Replication

Documents changes are persisted to Filecoin via web3.storage, and made available over IPFS and on a global content delivery network. All you need to do to sync state is send a link to the latest database head, and Fireproof will take care of the rest.

Peer-to-peer Sync

Application instances can be connected using WebRTC or any other stream API library, like Socket Supply, libp2p, or PartyKit. The first sync demo uses pure WebRTC with no signaling server, which limits its usability. There are demos with other transports coming soon.

Self-sovereign Identity

Fireproof is so easy to integrate with any site or app because you can get started right away, and set up an account later. By default users write to their own database copy, so you can get pretty far before you even have to think about API keys. Authorization is via non-extractable keypair, like TouchID / FaceID.

Thanks 🙏

Fireproof is a synthesis of work done by people in the web community over the years. I couldn't even begin to name all the folks who made pivotal contributions. Without npm, React, and VS Code all this would have taken so much longer. Thanks to everyone who supported me getting into database development via Apache CouchDB, one of the original document databases. The distinguishing work on immutable data-structures comes from the years of consideration IPFS, IPLD, and the Filecoin APIs have enjoyed.

Thanks to Alan Shaw and Mikeal Rogers without whom this project would have never got started. The core Merkle hash-tree clock is based on Alan's Pail, and you can see the repository history goes all the way back to work begun as a branch of that repo. Mikeal wrote the prolly trees implementation.

Contributing

To contribute please follow these steps for local setup and installation of the project

Click on the "Fork" button in the top-right corner of the repository's page. This will create a copy of the repository in your account.
Clone the forked repository to your local machine using Git.
Now cd to the target directory, or load the directory in your IDE, and open up a terminal.
Run the command pnpm install. This will install all the dependencies that are listed in the package.json file.
Now change the directory to packages/fireproof using the command cd packages/fireproof.
See the package.json file to work with all the listed commands and try them out. You can also test your changes using npm test.
Also change directory to examples/todomvc and run the command npm run dev to load up a simple application to understand the use of Fireproof as a real-time database.
Keep contributing :) See issues for ideas how to get started.