Configure a Synced Realm - React Native SDK

AppProvider

The @realm/react AppProvider gives you access to an instance of your App Services App.

To set up your App client, pass the App ID string to the id prop of AppProvider. Wrap any components that need to access the App with the AppProvider.

import React from 'react';
import {AppProvider} from '@realm/react';
function AppWrapper() {
  return (
    <View>
      <AppProvider id={APP_ID}>
        <MyApp />
      </AppProvider>
    </View>
  );
}

You can find more information about AppProvider on the Connect To Atlas App Services page.

UserProvider

UserProvider gives you access to a Realm user. A UserProvider is required for an app to use the hooks.

First, you need to configure user authentication with AppProvider and UserProvider. Then, work with authentication using the useApp() and useUser() hooks.

To set up user authentication:

1. Wrap all components you want to use with App Services in an AppProvider.

2. Inside of AppProvider, wrap all components that need access to an authenticated user with a UserProvider.

3. In UserProvider, include a fallback prop with another component that logs a user in. The app renders this component if there is no authenticated user.

4. In the component passed to the UserProvider.fallback prop, authenticate a user with Realm.App.logIn(), which you can access with the useApp() hook.

Components wrapped by UserProvider only render if your app has an authenticated user. These components can access the authenticated user with the useUser() hook.

import React from 'react';
import {useApp, UserProvider, AppProvider} from '@realm/react';
import {Button} from 'react-native';
function AppWrapper() {
  return (
    <AppProvider id={APP_ID}>
      {/* If there is no authenticated user,
          the app mounts the `fallback` component.
          Once the user successfully authenticates,
          the app unmounts the component in the
          `UserProvider.fallback` prop
          (the `LogIn` component in this example). */}
      <UserProvider fallback={LogIn}>
        {/* Components with access to the user.
            These components only mount
            if there's an authenticated user.*/}
        <RestOfApp />
      </UserProvider>
    </AppProvider>
  );
}
function LogIn() {
  const app = useApp();
  // This example uses anonymous authentication.
  // However, you can use any authentication provider
  // to log a user in with this pattern.
  async function logInUser() {
    await app.logIn(Realm.Credentials.anonymous());
  }
  return (
    <Button
      title='Log In'
      onPress={logInUser}
    />
  );
}

You can find more information about UserProvider on the Authenticate Users page.

RealmProvider

RealmProvider is a wrapper that exposes a realm to its child components. You configure your realm by passing props to RealmProvider.

When RealmProvider is rendered, it opens the realm. This means that the child components can't access the realm if rendering fails.

To configure a synced realm:

1. Import providers from @realm/react.

2. Configure AppProvider.

3. Configure UserProvider and nest it within AppProvider.

4. Pass your object models to RealmProvider's schema prop.

5. Create a FlexibleSyncConfiguration object.

6. Pass your SyncConfiguration object to the sync prop or add the object in-line.

7. Set up initial subscriptions or create a new subscription in RealmProvider child components.

8. Add other Configuration object properties as props to RealmProvider to further configure your realm.

import React from 'react';
import {AppProvider, UserProvider, RealmProvider} from '@realm/react';
function AppWrapperSync() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          schema={[YourObjectModel]}
          sync={{
            flexible: true,
            initialSubscriptions: {
              update(subs, realm) {
                subs.add(realm.objects(YourObjectModel));
              },
            },
          }}>
          <RestOfApp />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
}

For more information about configuring and using RealmProvider, check out the Configure a Realm page.

Open Synced Realm at Specific Path

Using AppConfiguration.baseFilePath, and Realm.BaseConfiguration.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 set, then metadata is stored in <Realm.defaultPath>/mongodb-realm.

Where, exactly, your Realm file is stored can vary depending on how you set Realm.BaseConfiguration.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 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.