@fireproof/partykit

@fireproof/partykit

Fireproof is an embedded JavaScript document database that runs in the browser (or anywhere with JavaScript) and connects to any cloud.

🎈 PartyKit is a realtime connection library that's the perfect complement to Fireproof's verifiable sync.

Get started

We assume you already have an app that uses Fireproof in the browser, and you want to setup collaboration among multiple users via the cloud or peer-to-peer. To write your first Fireproof app, see the Fireproof quickstart, othwerwise read on. It's also easy to add Fireproof to PartyKit apps, check out this demo repo for live magnetic poetry with database persistence.

PartyKit uses websockets and CloudFlare workers to manage a real-time group. Adding Fireproof requires one-line of config, and it syncs in its own party so you can use it with your existing PartyKit apps without impacting existing code.

1. Install

In your existing Fireproof app install the connector:

npm install @fireproof/partykit

2. Configure

If you already have PartyKit configured in your project, all you need to do is add one line to the config defining a fireproof party.:

{
  "name": "my-app-name",
  "main": "src/partykit/server.ts",
  "parties": {
    "fireproof": "node_modules/@fireproof/partykit/src/server.ts"
  }
}

If you haven't added PartyKit to your app, you want to run the PartyKit CLI to set up the basics:

npx partykit init

Refer to the PartyKit docs for more info on configuring PartyKit.

3. Connect

You're all done on the server, and ready to develop locally and then deploy with no further changes. Now you just need to connect to the party in your client code:

// you already have this in your app
import { useFireproof } from "use-fireproof";
// add this line
import { connect } from "@fireproof/partykit";

Now later in your app connect to the party (be sure to do this a component that runs on every render, like your root component or layout):

const { database } = useFireproof('my-app-database-name')
const connection = connect(database, '', process.env.NEXT_PUBLIC_PARTYKIT_HOST!)

The connect function is idempotent, and designed to be safe to call on every render. It takes three arguments, the current database, the remote database name, and the host of your PartyKit server. This will be the same host you are using in your app when calling usePartySocket and other PartyKit APIs, so once you have it set, you won't need to think about it again.

4. Collaborate

Now you can use Fireproof as you normally would, and it will sync in realtime with other users. Any existing apps you have that use the live query or subscription APIs will automatically render multi-user updates.

Remix connectors

In this example we use both the S3 and PartyKit connectors. You can use any combination of connectors in your app.

function partykitS3({ name, blockstore }: Connectable, partyHost?: string, refresh?: boolean) {
  if (!name) throw new Error("database name is required");
  if (!refresh && partyCxs.has(name)) {
    return partyCxs.get(name)!;
  }
  const s3conf = {
    // example values, replace with your own by deploying https://github.com/fireproof-storage/valid-cid-s3-bucket
    upload: "https://04rvvth2b4.execute-api.us-east-2.amazonaws.com/uploads",
    download: "https://sam-app-s3uploadbucket-e6rv1dj2kydh.s3.us-east-2.amazonaws.com",
  };
  const s3conn = new ConnectS3(s3conf.upload, s3conf.download, "");
  s3conn.connectStorage(blockstore);

  if (!partyHost) {
    console.warn("partyHost not provided, using localhost:1999");
    partyHost = "http://localhost:1999";
  }
  const connection = new ConnectPartyKit({ name, host: partyHost } as ConnectPartyKitParams);
  connection.connectMeta(blockstore);
  partyCxs.set(name, connection);
  return connection;
}