(DOCSP-26995) Reframe RN SDK open and close realm page

[krollins-mdb]

Pull Request Info

The Open and Close a Realm page needed a nearly complete overhaul because these concepts are very different with @realm/react.

I plan to re-evaluate the "Key Concept" section after we've finished the current Realm React epic.

Jira

• https://jira.mongodb.org/browse/DOCSP-26995

Staged Changes

• Configure a Realm

Reminder Checklist

If your PR modifies the docs, you might need to also update some corresponding
pages. Check if completed or N/A.

• Create Jira ticket for corresponding docs-app-services update(s), if any
• Checked/updated Admin API
• Checked/updated CLI reference

Review Guidelines

REVIEWING.md

Animal wearing a hat

[github-actions]

Readability for Commit Hash: 1726539

You can see any previous Readability scores (if they exist) by looking
at the comment's history.

Flesch Reading Ease scores for changed documents:

• source/sdk/react-native: 39.53
• source/sdk/react-native/realm-database: -118.88
• source/sdk/react-native/realm-database/bundle: 68.16
• source/sdk/react-native/realm-database/configure-a-realm: 73.37
• source/sdk/react-native/realm-database/encrypt: 55.34
• source/sdk/react-native/realm-database/overview: 52.6

The following table can be helpful in assessing the readability score of a document.

Score	Difficulty
90-100	Very Easy
80-89	Easy
70-79	Fairly Easy
60-69	Medium
50-59	Fairly Hard
30-49	Hard
0-29	Very Hard

[mongodben]

why is this file Models/index.js, not just Models.js?

[krollins-mdb]

Because it's the entry point for the directory and we can import like this:
import {RealmContext} from '../Models';

We could specify Models.js, but we use the index.js pattern in our demo apps.

[mongodben]

Because it's the entry point for the directory and we can import like this:
import {RealmContext} from '../Models';

you could also achieve this with the following:

// Models.js

const RealmContext = someObject;

export RealmContext;

i'd rec not using the index.js file. to my knowledge, you usually only have an index file if there are other files in the directory that you want to export.

---

for example this pattern would make more sense if you had the following structure:

Models
|__ index.js
|__ Model1.js
|__ Model2.js

and then you wanted to export both Model1 and Model2 from Models, so the import would look like:

// someOtherFile.js
import {Model1, Model2} from './Models';

[mongodben]

also now that i think more about it, it doesn't necessarily make sense to export realmContext from a file/directory called 'Models'. The configuration. contains more than the models/schema. also other stuff like in memory, encrypted ,etc.

perhaps rename the file RealmConfig.js?

[krollins-mdb]

Ah, yeah. That makes a lot of sense. I've renamed to RealmConfig.js and moved it to the root of the __tests__ directory. RealmConfig.js should make this much easier to understand. Thanks for helping me think this through!

[mongodben]

Suggested change

	Open more than one realm
	Open Multiple Realms

[krollins-mdb]

Agh. This title casing on headings. I'll get it eventually. Old habits die hard.

I think I'm going to go with "Open One or More Realms" though. Because you might want to open just two. And two is not multiple.

[mongodben]

in that case, what about 'More than One' like you originally had it?

since you already talk about just the 'one realm' case above

[mongodben]

i think this section should probably be removed. to really get going w device sync, you need some more context, like app creation on the backend, enable flexible sync, etc.

this probably needs to be a different page. see flutter and swift sdks for example.

while it's def important to mention opening a synced realm on this page, i think it'd suffice to point to the 'open a synced realm' on this page. looks like there's already a ticket for @realm/reactifing that page, DOCSP-27009/).

to borrow some text for this section, you can see what's on the flutter page.

[krollins-mdb]

Yeah, that makes a lot of sense. Thanks for pointing this out.

[mongodben]

i think we can consolidate these paragraphs a fair bit. first, i think this page and the intro for it should focus much more on only local realms. and with that focus, i think the flow of the info could be more streamlined to something like:

Suggested change

	The ``@realm/react`` library uses `React Context objects <https://reactjs.org/docs/context.html>`__
	to create and configure realms. You can access realms with React hooks.
	``@realm/react`` automatically opens and closes realms for you. To manage how it
	does so, you need to pass props to the ``@realm/react`` Context Providers:
	- ``<AppProvider>``
	- ``<UserProvider>``
	- ``<RealmProvider>``
	For Flexible Sync realms, you need all three Providers, nested in the order above.
	For local-only realms, you only need ``<RealmProvider>``.
	The ``@realm/react`` library exposes realms throughout your application with `React Context objects <https://reactjs.org/docs/context.html>`__ and Provider components. You can access realms with React hooks.
	To open a local realm, create a Context with the realm's configuration. The Context exports a `RealmProvider` component that exposes a realm with the configuration passed to the Context. All child components of the `RealmProvider` can access the realm using hooks.
	To learn how to open a realm using Device Sync, refer to :ref:`Open a Synced Realm <TODO: add relevant ref>`.

[mongodben]

note: this relates to below comment https://github.com/mongodb/docs-realm/pull/2529/files#r1090797122

[mongodben]

great start! some higher level comments about documenting opening synced realm and nits throughout.

didn't focus much on code review in this pass since there might be non-trivial changes to what's included here. will give that a more thorough review once we're more settled on the copy.

[mongodben]

rather than these 2 sections being under 'Configure a Realm with RealmProvider', i think it'd make more sense for these to be subsections of the 'Create a Context Object with createRealmContext' section since they're just about creating that context

[mongodben]

Suggested change

	Configure a Realm with ``<RealmProvider>``
	Expose a Realm with ``<RealmProvider>``

not sure if 'configure' is the right word here since you're not actually making and config here. maybe 'expose' better?

[krollins-mdb]

You're right. The config happens in the previous section. I've updated locally. Will be in my next commit.

[takameyer]

Looks great. One heads up, I do have a PR which will allow one to use a default Context like so:

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

const AppWrapper = () => {
  return (
    <RealmProvider schema={[Item]} inMemory={true}>
      <App/>
    </RealmProvider>
  )
};

This would make the createRealmContext an advanced use case when a user wants to use more than one Realm.

[mongodben]

nice improvements! back to you w some smaller items throughout.

[krollins-mdb]

@takameyer, thank you! That's good to know about. I've created a Jira ticket to refactor this page when the new pattern has been released.

[mongodben]

nitish: could you put this in the ts/realm-database directory?

imo looks a little funky/confusing that when you import it in the code examples in the docs, the import statement goes up a few directories. ex https://github.com/mongodb/docs-realm/pull/2529/files#diff-d50bcaa212383b262a507ceb3c0ef3c1761c093178a30c94387946ea90cf3c9eR4

[mongodben]

lgtm w a couple small things! nice work on this tricky one!