Quick Start

We'll run through a few basic concepts to get you started with your first real-time collaborative app with FireSync.

Setting up Firesync Backend

There are two ways to run FireSync

• FireSync Cloud - fully hosted instance which requires minimal setup.
• FireSync Server - A firesync-server you run on your own infastructure.

Authentication

Your backend should sign a JSON Web Token (JWT) for your client to pass to FireSync for access:

Node.js

import jwt from "jsonwebtoken";

const payload = {
  docs: {
    // Grant write access to the document called 'foo' and readonly access to 'bar'
    foo: "write",
    bar: "read",
  },
};

// Configure your secret via FS_JWT_AUTH_SECRET in firesync-server,
// or find it in your project settings for FireSync Cloud
const secret = "/B?E(H+KbPeShVmYq3t6w9zDC&F)J@Nc";

// Pass token to your client
const token = jwt.sign(payload, secret);

Python

import jwt

payload = {
  'docs': {
    # Grant write access to the document called 'foo' and readonly access to 'bar'
    'foo': 'write',
    'bar': 'read'
  }
}

# Configure your secret via FS_JWT_AUTH_SECRET in firesync-server,
# or find it in your project settings for FireSync Cloud
secret = '/B?E(H+KbPeShVmYq3t6w9zDC&F)J@Nc'

# Pass token to your client
token = jwt.encode(payload, secret)

See the Authentication Guide for more details

Client Setup

First install the FireSync client:

npm install @firesync/client --save

If we pass our JWT from above into the FireSync client, we will be able subscribe to the document called 'foo', and any edits we make will be immediately synced to any other clients subscribed to 'foo'

FireSync Cloud

import FireSync from "@firesync/client";
const firesync = new FireSync({
  projectName: "acme-dev", // Your project name in FireSync Cloud
  token: token, // JWT token Generated above from your server
});

const doc = firesync.subscribeYDoc("foo");

// Get a real-time map that we can set key, value pairs on
const map = doc.getMap("bar");
map.on("update", () => {
  // Triggered on either local updates, or updates from other clients
  console.log("Map was updated: ", map.toJSON());
});

// Set some values locally that will be synced to all clients
map.set("name", "Bob");
map.set("age", 42);
map.set("awesome", true);

FireSync Server

import FireSync from "@firesync/client";
const firesync = new FireSync({
  baseUrl: "http://localhost:5000", // The URL where firesync-server is running
  token: token, // JWT token Generated above from your server
});

const doc = firesync.subscribeYDoc("foo");

// Get a real-time map that we can set key, value pairs in
const map = doc.getMap("bar");
map.on("update", () => {
  // Triggered on either local updates, or updates from other clients
  console.log("Map was updated: ", map.toJSON());
});

// Set some values locally that will be synced to all clients
map.set("name", "Bob");
map.set("age", 42);
map.set("awesome", true);

The doc returned by firesync.subscribe is a Yjs doc that supports complex data structures with nested maps, lists and rich-text types.