Docs Menu
Docs Home
/ /
Atlas Device SDKs
/

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.

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.

1

To get started, clone the example app repository, checkout the example app branch, and navigate to the example project:

git clone https://github.com/realm/realm-js.git
cd realm-js
git checkout nh/wasm/emscripten_target
cd examples/example-react-task
2

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.

3

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:

src/atlas-app-services/config.json
{
"ATLAS_APP_ID": "myapp-abcde"
}
4

Now that you've installed dependencies and defined the connection to your App, you can run the example app:

npm start

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
}
};

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 at the top of your source files where you interact with the database:

import Realm, { App } from "realm";

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>" });

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);

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",
};

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}"`)
);
},
},
},
});

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]
});

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);
});

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");

Call the Realm.close() method when done with a realm instance to avoid memory leaks.

// Close the realm.
realm.close();

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.

← Quick Start with React