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

Realm is now Atlas Device SDK – Learn More

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.

Important

Only Applies to Local Realms

The content on this page only applies to local realms.

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.

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.

You should use the realm package to create your bundle rather than @realm/react.

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

import Realm from "realm";
import { Dog } from "./schemas";
// 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 up the android folder generated by React Native in Android Studio.
In the Project tree, navigate to app > src > main. Right click the main directory. Create a new subdirectory named assets.
Drag the bundled realm file into the assets directory.

In Xcode, open up the your_project_name.xcworkspace file inside of the ios directory generated by React Native.
Select your app in the project navigator and select the Build Phases tab in the project overview.
Expand the Copy Bundle Resources item.
Click the + icon.
Click the Add Other... button.
Find your bundled realm file and add it. Don't change the default settings, then select the Finish button.

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.

import React from 'react';
import {createRealmContext, Realm} from '@realm/react';
import {Dog} from './schema';
Realm.copyBundledRealmFiles();
const realmContext = createRealmContext({schema: [Dog], path: 'bundle.realm'});
const {RealmProvider} = realmContext;
export default function OpenBundledRealm() {
  return (
    <RealmProvider>
      {/* Rest of app has access to objects pre-populated
          in the bundled realm. */}
      <RestOfApp />
    </RealmProvider>
  );
}

Back

Configure a Realm

Encrypt a Realm