dexie-cloud-addon

Add-on (plugin) for connecting Dexie database with a database in the cloud, Dexie Cloud. The add-on is loaded on the client and integrates with Dexie to track changes, sync, authenticate and observe remote changes.

Installation

Install dexie-cloud-addon

npm install dexie@latest
npm install dexie-cloud-addon@latest

Create a cloud database to sync with

Use dexie-cloud (another package) to create a database in the cloud, so that dexie-cloud-addon will have a database URL to sync with. Dexie Cloud has a forever free edition for 3 production users, unlimited devices and unlimited evaluation users.

npx dexie-cloud create

Usage

import Dexie from 'dexie';
import dexieCloud from 'dexie-cloud-addon'; // Import the addon

const db = new Dexie('mydb', {
  addons: [dexieCloud] // Include addon in your Dexie instance
});

db.version(1).stores({
  myTable: '@myId, myIndex1, myIndex2, ...'
});

db.cloud.configure({
  databaseUrl: 'https://xxxxxxx.dexie.cloud', // URL from `npx dexie-cloud create`
  ...otherOptions
});

API

Methods

Method	Description
db.cloud.configure()	Connect your client to the cloud
db.cloud.login()	Authenticate user. Useful in combination with option `{requireAuth: false}`
db.cloud.logout()	Logout current user.
db.cloud.sync()	Force a sync. Useful in combination with option {disableWebSocket: true} and {disableEagerSync: true}
db.cloud.permissions()	Observe access permissions for given object - see also usePermission()

Properties

Property	Type	Description
db.cloud.version	string	Version of dexie-cloud-addon
db.cloud.options	DexieCloudOptions	Options configured using db.cloud.configure()
db.cloud.schema	DexieCloudSchema	Dexie-Cloud specific schema (complementary to dexie schema)
db.cloud.currentUserId	string	UserID of the currently logged in user
db.cloud.currentUser	Observable<UserLogin>	Observable of currently logged in user.
db.cloud.webSocketStatus	Observable<string>	Observable of websocket status: "not-started", "connecting", "connected", "disconnected" or "error"
db.cloud.syncState	Observable<SyncState>	Observable of sync state
db.cloud.persistedSyncState	Observable<PersistedSyncState>	Observable of persisted sync state
db.cloud.events.syncComplete	Observable<void>	Observable of persisted sync state
db.cloud.userInteraction	Observable<DXCUserInteraction>	Observable of login GUI. Use in combination with option `{customLoginGui: true}`
db.cloud.invites	Observable<Invite[]>	Observable of invites from other users to their realms
db.cloud.roles	Observable<Role[]>	Observable of global roles in your database
db.cloud.usingServiceWorker	boolean	Whether service worker is used or not. Depends on a combination of config options and whether a service worker that imports dexie-cloud's service worker module was found

Consuming Observable<T>

Many properties in db.cloud are Observables and the method db.cloud.permissions() returns an Observable. Observables represents reactive data and allows your app to subscribe to them and re-render whenever they emit a value. Observables can be consumed in any GUI framework and we give two samples below.

Example (React)

import { useObservable } from 'dexie-react-hooks';
import { db } from './db.js';

function MyComponent() {
  // db.cloud.invites is an Observable of Invite[] array.
  const invites = useObservable(db.cloud.invites);

  return (
    <>
      <h1>Invites</h1>
      <ul>
        {invites.map((invite) => (
          <li key={invite.id}>
            You are invited to act as {invite.roles?.join(', ')}
            in the realm {invite.realm.name}
            <button onClick={() => invite.accept()}>Accept</button>
            <button onClick={() => invite.reject()}>Reject</button>
          </li>
        ))}
      </ul>
    </>
  );
}

This component would render the current invites for your user at any time and re-render whenever an invite is added, updated or removed.

See useObservable()

Example (Svelte)

<script>
  import { db } from "./db.js";

  let oInvites = db.cloud.invites;
</script>

<div>
  <h1>Invites</h1>
  {#each $oInvites as invite (invite.id)}
    <li>{invite.realm.name}</li>
  {/each}
</div>

For more samples, see also db.cloud.currentUser and db.cloud.permissions()

Documentation