Docs Menu

Bundle a Realm File - Node SDK

On this page

  • Overview
  • Create a Realm File for Bundling
  • Bundle a Realm File in Your Production Application
  • Open a Realm from a Bundled Realm File
  • 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.

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

See the Bundle a Synchronized Realm section for details on considerations and limitations when bundling a synchronized realm.

  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

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.

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

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);

Generally, bundling a synchronized realm works the same as bundling a local-only realm. However, there are some limitations to bundling realms that use Realm 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.
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.
←  Manual Client Reset Data Recovery - Node SDKUpgrade from Stitch to Realm - Node.js SDK →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.