Skip to content

Commit 9a7010e

Browse files
adityaoberaiadityaoberai
committed
Add rxdb integration guide
1 parent 1a92b8a commit 9a7010e

File tree

3 files changed

+176
-0
lines changed

3 files changed

+176
-0
lines changed

‎src/routes/integrations/replication-rxdb/+page.markdoc

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
layout: integration
3+
title: Data replication with RxDB
4+
description: Setup push-pull replication from a local database and enable offline sync capabilities using RxDB
5+
date: 2025-04-17
6+
featured: false
7+
isPartner: true
8+
isNew: true
9+
cover: /images/integrations/replication-rxdb/cover.png
10+
category: databases
11+
product:
12+
avatar: '/images/integrations/avatars/rxdb.png'
13+
vendor: Upstash
14+
description: 'RxDB (Reactive Database) is a local-first, NoSQL database for JavaScript applications.'
15+
platform:
16+
- 'Self-hosted'
17+
- 'Cloud'
18+
images:
19+
- /images/integrations/replication-rxdb/cover.png
20+
---
21+
22+
RxDB (Reactive Database) is a client-side, NoSQL database designed for JavaScript applications. It emphasizes real-time data synchronization, offline-first capabilities, and reactive programming paradigms. RxDB is particularly suited for applications that require seamless user experiences across various platforms, including web browsers, mobile devices, and desktop environments.
23+
24+
# How does the integration work?
25+
26+
RxDB integrates with Appwrite through a replication plugin that enables two-way data synchronization between a client-side RxDB instance and an Appwrite Database. This setup allows apps to store data locally (using data stores such as LocalStorage, SQLite, or IndexedDB) and push/pull changes from the Appwrite backend. When offline, the app continues to function smoothly using RxDB's local-first model, and once connectivity is restored, it syncs changes with Appwrite. Conflict handling, soft deletion, and live replication are handled seamlessly using RxDB’s built-in tools and Appwrite’s Realtime API.
27+
28+
# How to implement
29+
30+
To implement the RxDB integration, there are several steps you must complete:
31+
32+
## Step 1: Configure Appwrite project
33+
34+
For this step, you must [create an account on Appwrite Cloud](https://cloud.appwrite.io/register) or [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven’t already. Head over to the Appwrite console, go to the **Settings** page, and copy your project ID and API endpoint for further usage. Next, go to the **Databases** page from the left sidebar, create a new database with the ID `mydb`, and then a collection with the ID `humans` (save both IDs for further usage).
35+
36+
Click on the **Attributes** tab and add the following attributes (schema used for demo purposes):
37+
38+
| Key | Type | Size | Required |
39+
| --- | --- | --- | --- |
40+
| `name` | String | 100 | Yes |
41+
| `age` | Integer | | Yes |
42+
| `homeAddress` | String | 2000 | Yes |
43+
| `deleted` | Boolean | | Yes |
44+
45+
> **Note:** The `deleted` attribute is necessary to add because RxDB only soft deletes to prevent data loss in offline scenarios (no hard deletion of data occurs).
46+
47+
Then, head to the **Settings** tab of your collection, scroll down to the **Permissions** section, and the following:
48+
49+
| Role | Create | Read | Update | Delete |
50+
| --- | --- | --- | --- | --- |
51+
| Any | Yes | Yes | Yes | Yes |
52+
53+
> **Note:** While RxDB does not allow you to manually configure permissions for each document, if your app uses Appwrite Auth and document-level permissions are enabled for your collection, the Appwrite SDK will automatically assign read and write permissions to the logged-in user for each document created.
54+
55+
## Step 2: Install Appwrite Web SDK and RxDB library
56+
57+
Open the terminal in your app’s working directory and run the following command:
58+
59+
```bash
60+
npm install appwrite rxdb
61+
```
62+
63+
In your app’s `.env` file, add the following:
64+
65+
```bash
66+
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
67+
APPWRITE_PROJECT_ID=your-project-id
68+
APPWRITE_DATABASE_ID=your-database-id
69+
APPWRITE_COLLECTION_ID=your-collection-id
70+
```
71+
72+
Then, import all necessary libraries in your code:
73+
74+
```js
75+
import { replicateAppwrite } from 'rxdb/plugins/replication-appwrite';
76+
import { createRxDatabase, addRxPlugin, RxCollection } from 'rxdb/plugins/core';
77+
import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage';
78+
import { Client } from 'appwrite';
79+
```
80+
81+
## Step 3: Setup Appwrite client
82+
83+
To create an Appwrite client, add the following code:
84+
85+
```js
86+
export const client = new Client()
87+
.setEndpoint(process.env.APPWRITE_ENDPOINT)
88+
.setEndpointRealtime(process.env.APPWRITE_ENDPOINT)
89+
.setProject(process.env.APPWRITE_PROJECT_ID);
90+
```
91+
92+
## Step 4: Create an RxDB database and collection
93+
94+
To create an RxDB database and collection, first, you must prepare a database schema via the following code:
95+
96+
```js
97+
const mySchema = {
98+
title: 'my schema',
99+
version: 0,
100+
primaryKey: 'id',
101+
type: 'object',
102+
properties: {
103+
id: {
104+
type: 'string',
105+
maxLength: 100
106+
},
107+
name: {
108+
type: 'string'
109+
},
110+
age: {
111+
type: 'number'
112+
},
113+
homeAddress: {
114+
type: 'string'
115+
}
116+
},
117+
required: ['id', 'name', 'age', 'homeAddress']
118+
};
119+
```
120+
121+
Using this schema, you can create a database and collection via the following code:
122+
123+
```js
124+
const db = await createRxDatabase({
125+
name: 'mydb',
126+
storage: getRxStorageLocalstorage()
127+
});
128+
129+
await db.addCollections({
130+
humans: {
131+
schema: mySchema
132+
}
133+
});
134+
135+
const collection = db.humans;
136+
```
137+
138+
> **Note:** Please ensure that the names of your RxDB database and collection match the IDs of your Appwrite database and collection.
139+
>
140+
141+
## Step 5: Start replication
142+
143+
To start data replication, add the following code:
144+
145+
```js
146+
const replicationState = replicateAppwrite({
147+
replicationIdentifier: 'my-appwrite-replication',
148+
client,
149+
databaseId: process.env.APPWRITE_DATABASE_ID,
150+
collectionId: process.env.APPWRITE_COLLECTION_ID,
151+
deletedField: 'deleted', // Field that represents deletion in Appwrite
152+
collection,
153+
pull: {
154+
batchSize: 10,
155+
},
156+
push: {
157+
batchSize: 10
158+
},
159+
/*
160+
* ...
161+
* You can set all other options for RxDB replication states
162+
* like 'live' or 'retryTime'
163+
* ...
164+
*/
165+
});
166+
```
167+
168+
With that, your RxDB integration is configured and you can use other relevant RxDB functionalities and database operations in your application.
169+
170+
# Further resources
171+
172+
If you would like to learn more about RxDB and Appwrite Databases, we have some resources that you should visit:
173+
174+
- [RxDB docs for Appwrite](https://rxdb.info/replication-appwrite.html)
175+
- [Build an offline-first journal app with RxDB and Appwrite](/blog/post/offline-first-journal)
176+
- [Offline-first journal demo app on GitHub](https://github.com/appwrite-community/offline-journal)

‎static/images/integrations/avatars/rxdb.png

2.51 KB
Loading

‎static/images/integrations/replication-rxdb/cover.png

998 KB
Loading

0 commit comments

Comments
 (0)