Bundled realm in React Native: docs are not clear about sync

MongoDB Atlas App Services & Realm Realm
1

There is docs page: Bundle a Realm File - React Native SDK. In the beginning there is a note:

Important
Only Applies to Local Realms
The content on this page only applies to local realms.

So, synced realms cannot be pre-bundled? However the top of the page mentions:

For synced realms, bundling can avoid a lengthy initial download…

And a bit below it is mentioned:

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

So it seems it is possible. Confusing.

Also, a bit below when RealmProvider is created the code looks like this:

const realmContext = createRealmContext({schema: [Dog], path: 'bundle.realm'});
const {RealmProvider} = realmContext;

This differs from the quickstart guide which recommends creating realm provider like this:

import {RealmProvider} from '@realm/react';

// ...

<RealmProvider schema={[Profile]}>
  <RestOfApp />
</RealmProvider>

So, it is possible to bundle synced realm? It didn’t work for me when I tried using the way recommended in quickstart, even though Realm.copyBundledRealmFiles(); didn’t throw any error.
And what’s the best way to create realm provider?

2

Hi A_U

Yes, it can be pre bundled. I’m actually sitting here laughing at this post, because I had a conversation with MongoDB Engineering over 4 years ago about this exact same issue lol. I even wrote on my dev blog about it about 3 years ago when it came up during a customer incident that had me working until 9:45 in the evening, and then again having to step into a call at 4am the following morning lol.

The following is a direct copy and paste from my blog on this exact topic, this forum won’t let me post more than one image, so a lot of it visually isn’t here but the code and stuff is.

Yes, you can bundle a synced realm, but there are important nuances:

  • Bundling a Synced Realm: Bundling a synced realm can be useful to avoid a lengthy initial download by providing a pre-populated dataset that is immediately available when the app is first launched. This can significantly improve the user experience, especially in cases where the initial sync might take time.

  • Only Applies to Local Realms (Confusion): The note stating that “the content on this page only applies to local realms” primarily refers to the process of bundling itself, which is simpler for local realms. For synced realms, additional steps are needed to ensure that the data in the bundled file is properly synchronized with the backend once the app is running.

This is how you bundle a synced realm:

To bundle a synced realm, follow these steps:

  1. Create the Synced Realm File:
  • Open the synced realm and add the data you want to bundle.
  • Allow enough time for the realm to fully sync with the backend.
  1. Copy the Realm File:
  • Once the realm has fully synced, copy the realm file from the device’s storage to your project, so it can be bundled with your app.
  1. Bundle the Realm File:
  • Include this realm file in your app’s assets, ensuring it will be available when the app is first launched.
  1. Use Realm.copyBundledRealmFiles() (in React Native):
  • This method will copy the bundled realm file from your assets directory to the appropriate location in the app’s data storage. This step is crucial for making the bundled realm file available for use.

Creating the Realm Provider

Regarding how to create the RealmProvider, both approaches you’ve mentioned are valid, but they serve slightly different purposes:

  1. Using createRealmContext:
  • createRealmContext is a utility that allows you to create a Realm context with more customization options, including specifying the path to the realm file (e.g., the bundled file).

This is what the code should look something like:

const realmContext = createRealmContext({schema: [Dog], path: 'bundle.realm'});
const {RealmProvider} = realmContext;

This is useful if you want to specify a custom path for the realm file, which is necessary when working with bundled realm files.
2. Using RealmProvider Directly:

  • The simpler approach recommended in the quickstart guide works well for cases where you don’t need to specify a custom path or other advanced configurations.

Here’s more code for your viewing of what to go for:

import {RealmProvider} from '@realm/react';

<RealmProvider schema={[Profile]}>
  <RestOfApp />
</RealmProvider>

This method uses the default realm configuration, which is typically sufficient for most use cases, especially when not dealing with a pre-bundled realm file.