Configure a Synced Realm - React Native SDK

On this page

Prerequisites

Configure a Flexible Sync Realm
Nest <RealmProvider> within <AppProvider> and <UserProvider>
Configure <RealmProvider>
Open Synced Realm at Specific Path
Access a Synced Realm While Offline
Access Immediately with Background Sync
Access After Timeout with Background Sync

You can configure a realm to automatically synchronize data between many devices that each have their own local copy of the data.

For more information about synced realms, including directions on how to set up sync in an App Services App, see Atlas Device Sync Overview.

Prerequisites

Before you configure a realm with Flexible Sync in a React Native application:

Enable Flexible Sync on the backend. You must configure Flexible Sync in the backend before you can use it with your client application.
Initialize the App client.
Authenticate a user in your client project.

Configure a Flexible Sync Realm

This section covers Flexible Sync realms. Flexible Sync is the preferred mode for new apps that use Atlas Device Sync.

For information about realms using the older Partition-Based Sync, refer to Partition-Based Sync.

By default, Realm syncs all data from the server before returning. If you want to sync data in the background, read the Configure a Synced Realm While Offline section.

Nest <RealmProvider> within <AppProvider> and <UserProvider>

To use a Flexible Sync realm with @realm/react, you must nest <RealmProvider> within <UserProvider>. And <UserProvider> must be nested in <AppProvider>. This ensures that <RealmProvider> has all of the context it needs, like a logged-in user.

Call createRealmContext() with your realm configuration to access RealmProvider in the return value.

The following example shows how to use these providers together in your app:

import React from 'react';
import {AppProvider, createRealmContext, UserProvider} from '@realm/react';
const realmContext = createRealmContext({
  schema: [Profile],
});
const {RealmProvider} = realmContext;
function AppWrapperSync() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          sync={{
            flexible: true,
            onError: console.error,
          }}>
          <RestOfApp />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
}

For more information about configuring and using <AppProvider>, check out the Connect To Atlas App Services page.

You can also find information about <UserProvider> on the Authenticate Users page.

Configure <RealmProvider>

To configure a Flexible Sync realm, use @realm/react's createRealmContext() function and its returned <RealmProvider>.

In a <RealmProvider> that's nested in a <UserProvider>, add a sync property with a SyncConfiguration object that contains flexible: true.

Note that <UserProvider> automatically passes an authenticated user to <RealmProvider>.

import React from 'react';
import {AppProvider, createRealmContext, UserProvider} from '@realm/react';
const realmContext = createRealmContext({
  schema: [Profile],
});
const {RealmProvider} = realmContext;
function AppWrapperSync() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          sync={{
            flexible: true,
            onError: console.error,
          }}>
          <RestOfApp />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
}

Important

Flexible Sync Requires a Subscription

You can't use a Flexible Sync realm until you add at least one subscription. To learn how to add subscriptions, refer to Add a Subscription.

Open Synced Realm at Specific Path

New in version realm@11.6.0.

Using AppConfiguration.baseFilePath, and Realm.Configuration.path, you can control where Realm and metadata files are stored on client devices.

To do so, set <AppProvider>.baseFilePath. If baseFilePath is not set, the current work directory is used. You can also set <RealmProvider>.sync.path for more control.

If baseFilePath is set, metadata is always stored in <baseFilePath>/mongodb-realm/. If baseFilePath isn't sßet, then metadata is stored in <Realm.defaultPath>/mongodb-realm.

Where, exactly, your Realm file is stored can vary depending on how you set Realm.Configuration.path:

Realm.Configuration.path is not set and baseFilePath is set. Your Realm file is stored at baseFilePath.
Realm.Configuation.path is set to a relative path. Your Realm file is stored relative to baseFilePath.
Realm.Configuration.path is an absolute path. Your Realm file is stored at Realm.Configuration.path.

Access a Synced Realm While Offline

The following subsections show how to use background synchronization to access a realm while offline. To do this, use a cached user and an OpenRealmBehaviorConfiguration object.

Within <RealmProvider>'s sync configuration, set the optional newRealmFileBehavior and existingRealmFileBehavior fields to your OpenRealmBehaviorConfiguration object to enable background synchronization.

You can open a realm immediately with background sync or after a timeout.

Note

Initial login requires a network connection

When a user signs up for your app, or logs in for the first time with an existing account on a client, the client must have a network connection. Checking for cached user credentials lets you open a realm offline, but only if the user has previously logged in while online.

Access Immediately with Background Sync

You may want to sync changes in the background to display partial data to the user while the synced realm downloads data from the server, preventing the user experience from being blocked. We recommend syncing changes in the background for applications in which the user's device may go offline. To sync changes in the background, open a synced realm synchronously.

Access After Timeout with Background Sync

If you want to sync data but you're in an environment where it's uncertain if the user has an Internet connection, specify a timeOut. This automatically opens the realm when either:

the timeout period elapses.
the realm has completely downloaded.

If the realm doesn't finish downloading before the timeout, the initial Sync continues in the background.

← Sync Data Between Devices - React Native SDK Manage Flexible Sync Subscriptions - React Native SDK →