Bundle a Realm File - React Native SDK

On this page

Procedure

Create a Realm File to Bundle
Bundle the Realm File with your App
Open the Bundled Realm in your App
Bundle a Synchronized Realm

Realm supports bundling realm files. When you bundle a realm file, you include a database and all of its data in your application download.

This allows users to start applications for the first time with a set of initial data. For synced realms, bundling can avoid a lengthy initial download the first time a user opens your application. Instead, users must only download the synced changes that occurred since you generated the bundled file.

Warning

Does Not Apply to Expo Apps

This procedure doesn't work for React Native apps created with Expo.

Procedure

Follow these steps to create and bundle a realm file for your React Native application. On a high level you:

Create a bundled realm file in a Node.js script.
Copy the bundled realm to the iOS and/or Android builds for your application.
Call Realm.copyBundledRealmFiles() before you open the bundled Realm in your React Native JavaScript code.

Note

Bundle Synchronized Realms

SDK version 10.12.0 introduced the ability to bundle synchronized realms. Before version 10.12.0, you could only bundle local realms.

For details on considerations and limitations when bundling a synchronized realm, see the Bundle a Synchronized Realm section.

Create a Realm File to Bundle

The easiest way to create a bundled realm for your React Native app is to write a separate Node.Js script to create the bundle.

Build a temporary realm app that shares the data model of your application.

Open a realm and add the data you wish to bundle. If using a synchronized realm, allow time for the realm to fully sync.

create-bundled-realm.js

// open realm
const config = {
  schema: [Dog],
  path: "bundle.realm",
};
const realm = await Realm.open(config);
// add data to realm
realm.write(() => {
  realm.create("Dog", { name: "Jasper", age: 10, type: "Golden Retriever" });
  realm.create("Dog", { name: "Maggie", age: 12, type: "Collie" });
  realm.create("Dog", { name: "Sophie", age: 6, type: "German Shepard" });
});
realm.close();

Note the filepath of the bundled realm file. You'll need this file to use the bundled realm in your production application, as described in the next section.

temp_realm_app

.
├── bundle.realm
... rest of files in _temp_ application

Bundle the Realm File with your App

Now that you have a copy of the realm that contains the initial data, add the bundled realm file to your production application. Where you place the bundled realm differs for iOS and Android builds.

Open the Bundled Realm in your App

The realm is now bundled and will be included when a user downloads the app. To add the bundled realm file to your app's document directory, call Realm.copyBundledRealmFiles() before you open the realm.

Realm.copyBundledRealmFiles() adds all *.realm files from the application bundle to the application documents directory. This method doesn't override any existing files with the same name, so it's safe to call every time the app starts.

Open the bundled realm with the same name and configuration that you specified when you initially created the bundled realm.

Now that you have a copy of the realm included with your production application, you need to add code to use it.

Realm.copyBundledRealmFiles();
realm = await Realm.open({
  schema: [Dog],
  path: 'bundle.realm',
});

Bundle a Synchronized Realm

Generally, bundling a synchronized realm works the same as bundling a local-only realm. However, there are some limitations to bundling realms that use Device Sync.

You can only bundle fully synchronized realms. Make sure that the realm has fully synchronized with the server before bundling:

const config = {
  sync: {
    user: app.currentUser,
    partitionValue: app.currentUser.id,
  },
  schema: [Car],
};
const realm = await Realm.open(config);
// create many changes
realm.write(() => {
  for (let i = 0; i < 25; i++) {
    realm.create("Car", {
      make: "Toyota",
      model: "Prius",
      miles: i,
      owner: app.currentUser.id,
    });
  }
});
// ensure synchronize all changes before copy
await realm.syncSession.uploadAllLocalChanges();
await realm.syncSession.downloadAllServerChanges();
// changes are synchronized -- we can copy the realm
realm.writeCopyTo(__dirname + "syncedCopy.realm");

When opening a bundled synchronized realm, you must use the same partition key that was used in the original realm. If you use a different partition key, the SDK throws an error when opening the bundled realm.

Warning

Synchronized Realm Bundling and Client Maximum Offline Time

If your application has enabled advanced backend compaction by configuring a client maximum offline time, users could experience a client reset the first time they open the bundled realm file. This can happen if:

the bundled realm file was generated more than client maximum offline time days before the user syncs the realm for the first time.

Users experiencing a client reset download the full state of the realm from the application backend. This negates the advantages of bundling a realm file. To prevent client resets and preserve the advantages of realm file bundling:

Avoid using a client maximum offline time in applications that bundle a synchronized realm.
If your application does use a client maximum offline time, ensure that your application download always includes a recently synchronized realm file. Generate a new file each application version, and ensure that no version ever stays current for more than client maximum offline time number of days.

← Encrypt a Realm - React Native SDK App Services - React Native SDK →