Configure a Realm - React Native SDK

Prerequisites

Before you configure a realm in a React Native application:

1. Install the Realm React Native SDK

2. Install the @realm/react package

Configure a Realm Without Sync

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 non-synced realm:

1. Import RealmProvider from @realm/react.

2. Pass your object models to the schema prop.

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

import React from 'react';
import {RealmProvider} from '@realm/react';
function AppWrapperLocal() {
  return (
    <RealmProvider schema={[YourObjectModel]}>
      <RestOfApp />
    </RealmProvider>
  );
}

For a list of providers and hooks used in non-synced realm, check out @realm/react Providers and Hooks.

import React from 'react';
import {Realm, RealmProvider} from '@realm/react';
function AppWrapperLocal() {
  return (
    <RealmProvider inMemory={true}>
      <RestOfApp />
    </RealmProvider>
  );
}

Configure a Synced Realm

To open a realm that synchronizes data with Atlas using Device Sync, refer to Open a Synced Realm.

Expose More Than One Realm

The @realm/react package exposes realms in your application using React Context objects and Provider components. You can access realms with React hooks.

To expose more than one realm, consider the following:

• Each realm needs its own Context object, created with createRealmContext().

• The providers and hooks within each context should be namespaced so that it's easy to reason about the realm you're working with.

• If you import RealmProvider directly from @realm/react, it is a separate Context object. That object's providers and hooks can't be unsynced with Context objects created using createRealmContext.

import React from 'react';
import {
  Realm,
  AppProvider,
  UserProvider,
  createRealmContext,
} from '@realm/react';
class SharedDocument extends Realm.Object {
  static schema = {
    name: 'SharedDocument',
    properties: {
      _id: 'objectId',
      owner_id: 'objectId',
      title: 'string',
      createdDate: 'date',
    },
    primaryKey: '_id',
  };
}
class LocalDocument extends Realm.Object {
  static schema = {
    name: 'LocalDocument',
    properties: {
      _id: 'objectId',
      name: 'string',
      createdDate: 'date',
    },
  };
}
// Create Shared Document context object.
const SharedRealmContext = createRealmContext({
  schema: [SharedDocument],
});
// Create Local Document context object.
const LocalRealmContext = createRealmContext({
  schema: [LocalDocument],
});

import React from 'react';
import {
  Realm,
  AppProvider,
  UserProvider,
  createRealmContext,
} from '@realm/react';
class SharedDocument extends Realm.Object<SharedDocument> {
  _id!: Realm.BSON.ObjectId;
  owner_id!: Realm.BSON.ObjectId;
  title!: string;
  createdDate?: Date;
  static schema: ObjectSchema = {
    name: 'SharedDocument',
    properties: {
      _id: 'objectId',
      owner_id: 'objectId',
      title: 'string',
      createdDate: 'date',
    },
    primaryKey: '_id',
  };
}
class LocalDocument extends Realm.Object<LocalDocument> {
  _id!: Realm.BSON.ObjectId;
  name!: string;
  createdDate?: Date;
  static schema: ObjectSchema = {
    name: 'LocalDocument',
    properties: {
      _id: 'objectId',
      name: 'string',
      createdDate: 'date',
    },
  };
}
// Create Shared Document context object.
const SharedRealmContext = createRealmContext({
  schema: [SharedDocument],
});
// Create Local Document context object.
const LocalRealmContext = createRealmContext({
  schema: [LocalDocument],
});

// Namespace the Shared Document context's providers and hooks.
const {
  RealmProvider: SharedDocumentRealmProvider,
  useRealm: useSharedDocumentRealm,
} = SharedRealmContext;
// Namespace the Local Document context's providers and hooks.
const {
  RealmProvider: LocalDocumentRealmProvider,
  useRealm: useLocalDocumentRealm,
} = LocalRealmContext;

function TwoRealmsWrapper() {
  return (
    <View>
      <AppProvider id={APP_ID}>
        <UserProvider fallback={LogIn}>
          {/* This is a Flexible Sync realm. */}
          <SharedDocumentRealmProvider sync={{flexible: true}}>
            <AppSectionOne />
          </SharedDocumentRealmProvider>
        </UserProvider>
      </AppProvider>
      {/* This is a separate local-only realm. */}
      <LocalDocumentRealmProvider>
        <AppSectionTwo />
      </LocalDocumentRealmProvider>
    </View>
  );
}
function AppSectionOne() {
  const realm = useSharedDocumentRealm();
  // Work with shared documents...
}
function AppSectionTwo() {
  const realm = useLocalDocumentRealm();
  // Work with local documents...
}

Access a Realm Without Providing a Schema

After a realm has been created on a device, you don't need to always pass in a schema to access the realm. Instead, you can use RealmProvider without passing any object models to its schema property. The realm's schema is derived from the existing realm file at Realm.defaultPath.

Accessing a realm without providing a schema only works for local realms. You must always pass a schema when using a Synced realm.

import React from 'react';
import {RealmProvider} from '@realm/react';
function AppWrapper() {
  return (
    // To access a realm at the default path, do not pass any configuration.
    // Requires a realm that has already been created.
    <RealmProvider>
      <RestOfApp />
    </RealmProvider>
  );
}

@realm/react Providers and Hooks

@realm/react has providers and hooks that simplify working with your non-sync realm and its data.

const realm = useRealm();

const myTask = useObject(Task, _id);

const tasks = useQuery(Task);