Get Started with Realm Web & Atlas Device Sync (Preview)
On this page
- Get Started with an Example App
- Get the Code
- Install Dependencies
- Create and Connect an App Services App
- Run the Example App
- Install & Set Up Manually
- Use Realm & Device Sync
- Import Realm
- Initialize an App
- Authenticate a User
- Define an Object Model
- Open a Realm
- Open a Non-Synced Realm
- Create, Modify, and Delete Realm Objects
- Find, Sort, and Filter Objects
- Close a Realm
- Limitations of Device Sync on Web
The Realm JavaScript SDK with WebAssembly support allows you to build realtime web applications for the browser using the Realm Database API and Atlas Device Sync.
Important
The Realm JS SDK with WebAssembly support is in Preview. It currently has significant limitations relative to the Realm JS SDK for Node.js or React Native. See the limitations section for more information.
Get Started with an Example App
The fastest way to start using the Realm JS WebAssembly SDK is to clone and run our pre-built Web Sync Example App. The app is written in React and uses Realm Database APIs and Atlas Device Sync.
Install Dependencies
From the example app's root directory, run the following command to install dependencies, including the Realm JS SDK with WebAssembly:
npm install
Note
The example app currently supports installation with npm
.
If you use yarn
or pnpm
then you may need to provide
additional polyfills.
Create and Connect an App Services App
To use Device Sync, you must connect to an App Services App that
has Device Sync enabled. Follow the App creation instructions in
the example project's README.md
file. Once you've created and
configured the App, copy its Client App ID and paste it into the
src/atlas-app-services/config.json
file in the example
project:
{ "ATLAS_APP_ID": "myapp-abcde" }
Install & Set Up Manually
You can install the Realm JS SDK with WebAssembly support from npm:
npm install realm@12.0.0-browser.2
Note
The Realm JS SDK with WebAssembly support is currently only
available as a tagged release of the realm
package on npm. You
must specify the exact version number and tag when installing the
SDK.
You'll also need to configure your project to use webpack with top-level await enabled. For example, your configuration should extend this base configuration:
module.exports = { experiments: { topLevelAwait: true } };
Use Realm & Device Sync
Once you've installed the Realm JS SDK with WebAssembly support and configured your application, you can use the SDK to build realtime web applications with Realm and Atlas Device Sync.
The examples in this section show how to work with Realm in your app.
Tip
If you're writing a React application, consider using the @realm/react package. It includes pre-built hooks and components that let you natively integrate Realm with React applications.
Import Realm
Import realm at the top of your source files where you interact with the database:
import Realm, { App } from "realm";
Initialize an App
Device Sync uses Atlas App Services to manage authentication and sync data between devices. To use Device Sync from your web app, you must connect to an App Services App that has Device Sync enabled.
You connect to an App using its client App ID. To learn how to get it, see Find Your App ID.
const app = new App({ id: "<your-app-id>" });
Authenticate a User
To authenticate a user, call the App.logIn()
method on your App
instance. You can log in with any authentication provider. For more
examples, see Authenticate a User.
const credentials = Realm.Credentials.anonymous(); await app.logIn(credentials);
Define an Object Model
Realm uses native JavaScript objects to model your application data. You define object types where all objects of a given type share a schema that controls the object's contents.
To define a Realm object type, create a schema object that specifies the
type's name
and properties
. The type name must be unique among
object types in a realm.
const TaskSchema = { name: "Task", properties: { _id: "int", name: "string", status: "string?", owner_id: "string?", }, primaryKey: "_id", };
Open a Realm
To open a synced realm, call Realm.open()
with a configuration
object that specifies the realm's schema and includes a sync
configuration object. The sync configuration should specify the
authenticated user and define initial subscriptions that control which
data is synced:
const realm = await Realm.open({ schema: [TaskSchema], sync: { user: app.currentUser, flexible: true, // Define initial subscriptions to start syncing data as soon as the // realm is opened. initialSubscriptions: { update: (subs, realm) => { subs.add( // Get objects that match your object model, then filter them by // the `owner_id` queryable field realm.objects(Task).filtered(`owner_id == "${anonymousUser.id}"`) ); }, }, }, });
Open a Non-Synced Realm
To open a local, in-memory realm that does not sync, call
Realm.open()
with a local realm configuration object:
const realm = await Realm.open({ schema: [TaskSchema] });
Create, Modify, and Delete Realm Objects
Once you have opened a realm, you can create, modify, and delete objects
in it. All write operations must occur within a Realm.write()
transaction block.
const allTasks = realm.objects(Task); // Add a couple of Tasks in a single, atomic transaction. realm.write(() => { realm.create(Task, { _id: 1, name: "go grocery shopping", status: "Open", }); realm.create(Task, { _id: 2, name: "go exercise", status: "Open", }); }); const task1 = allTasks.find((task) => task._id == 1); const task2 = allTasks.find((task) => task._id == 2); realm.write(() => { // Modify an object. task1!.status = "InProgress"; // Delete an object. realm.delete(task2); });
Find, Sort, and Filter Objects
You can query objects in a realm using the Realm.objects()
method.
Queries must specify the object type to query for. You can optionally
filter and sort the results of a query using a fluent method chaining
API.
// Query for specific obect using primary key. const specificTask = realm.objectForPrimaryKey(Task, 0); // Query realm for all instances of the "Task" type. const tasks = realm.objects(Task); // Filter for all tasks with a status of "Open". const openTasks = tasks.filtered("status = 'Open'"); // Sort tasks by name in ascending order. const tasksByName = tasks.sorted("name");
Close a Realm
Call the Realm.close()
method when done with a realm instance to
avoid memory leaks.
// Close the realm. realm.close();
Limitations of Device Sync on Web
Device Sync on the browser is currently subject to the following limitations:
No persistence: The Realm JS Web SDK does not persist Device Sync data to disk. All local data is stored in memory and will be lost when the browser tab is closed or refreshed.
No worker threads: You must perform all Realm operations on the main thread. You cannot open or work with a realm in a web worker thread.
No encryption at rest: The Realm JS Web SDK stores all local data at rest unencrypted in memory. Data in transit between the browser and the Device Sync server is encrypted over HTTPS.