Bundle a Realm File - Node SDK

Overview

To create and bundle a realm file with your application:

1. Create a realm file that contains the data you'd like to bundle.

2. Add the bundled realm file to your production application.

3. In your production application, open the realm from the bundled asset file. For synchronized realms, you must include the partition key.

Create a Realm File for Bundling

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

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

3. Use the writeCopyTo() method to copy the realm to a new file:

   const originalPath = path.join(__dirname, "original.realm");
   const originalConfig = {
     schema: [Car],
     path: originalPath,
   };
   const originalRealm = await Realm.open(originalConfig);
   const copyPath = path.join(__dirname, "copy.realm");
   originalRealm.writeCopyTo(copyPath);

   writeCopyTo() automatically compacts your realm to the smallest possible size before copying.

   Note

   Differences Between Synchronized Realms and Local-only Realms

   The above example uses a SyncConfiguration to configure a synchronized realm for the sync field of the Configuration. To create a copy of a local realm, do not include the sync field in your Configuration object.

4. Note the filepath of the bundled realm file, which can be found at the location specified in the argument passed to writeCopyTo() in the previous step. You'll need this file to use the bundled realm in your production application, as described in the next section.

   temp_realm_app

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

Bundle a Realm File in Your Production Application

Now that you have a copy of the realm that contains the initial data, bundle it with your production application.

Add the bundled realm file made in the previous section to your production application.

.
├── copyOfDefault.realm
... rest of files in _prod_ application

Open a Realm from a Bundled Realm File

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

Create a Configuration with the path to the bundled realm as the value for the path field. Pass that configuration to the Realm.open() method. Now you can work with the data from your bundled realm in the realm you've just opened.

const copyConfig = {
  schema: [Car],
  path: "path/to/bundled/file.realm"
};
const copyRealm = await Realm.open(copyConfig);

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.

1. 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");

2. 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.