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

## 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](https://docs-mongodbcom-staging.corp.mongodb.com/realm/docsworker-xlarge/DOCSP-26995/sdk/react-native/realm-database/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.

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

### Review Guidelines


[REVIEWING.md](https://github.com/mongodb/docs-realm/blob/master/REVIEWING.md)

### Animal wearing a hat


![](https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTC2T1wlVitCxsZHwKb18NazHbiFmtF0_FeNw&usqp=CAU)

---------

Co-authored-by: Ben Perlmutter <[email protected]>

config/redirects

@@ -1004,3 +1004,7 @@ raw: ${prefix}/sdk/dotnet/examples/work-with-users -> ${base}/sdk/dotnet/work-wi
 raw: ${prefix}/sdk/dotnet/advanced-guides  -> ${base}/sdk/dotnet/
 raw: ${prefix}/sdk/dotnet/advanced-guides/debugging -> ${base}/sdk/dotnet/
 raw: ${prefix}/sdk/dotnet/advanced-guides/testing -> ${base}/sdk/dotnet/
+
+# Realm React Guidance (https://jira.mongodb.org/browse/DOCSP-23395)
+
+raw: ${prefix}/sdk/react-native/realm-database/open-and-close-a-realm -> ${base}/sdk/react-native/realm-database/configure-a-realm

examples/react-native/README.md

@@ -18,6 +18,9 @@ This project uses [npm](https://www.npmjs.com/) to manage dependencies. To get s
 npm install
 ```
 
+> **Warning**
+> Currently, `npm install` fails in Node.js v16.17.0. We recommend using Node.js v16.14.0.
+
 ### Run Tests
 
 This project defines a unit test suite that tests both JS and TS code examples. You can run them via:

examples/react-native/__tests__/ts/RealmConfig.js

@@ -0,0 +1,27 @@
+// :snippet-start: create-realm-context
+import {createRealmContext} from '@realm/react';
+// Import all of your models.
+import Invoice from './Models/Invoice';
+import Business from './Models/Business';
+// :remove-start:
+import Address from './Models/Address';
+import Contact from './Models/Contact';
+// :remove-end:
+
+export const RealmContext = createRealmContext({
+  // Pass all of your models into the schema value.
+  schema: [Invoice, Business],
+});
+// :snippet-end:
+
+export const SecondRealmContext = createRealmContext({
+  // Pass all of your secondary models into the schema value.
+  schema: [Address, Contact],
+});
+
+// :snippet-start: in-memory-realm
+export const InMemoryRealmContext = createRealmContext({
+  schema: [Address, Contact],
+  inMemory: true,
+});
+// :snippet-end:

examples/react-native/__tests__/ts/realm-database/configure-realm-local.test.tsx

@@ -0,0 +1,39 @@
+// :snippet-start: configure-realm
+import React from 'react';
+import {RealmContext} from '../RealmConfig';
+// :remove-start:
+import {render} from '@testing-library/react-native';
+import {useApp} from '@realm/react';
+import {View, Text} from 'react-native';
+
+const APP_ID = 'example-testers-kvjdy';
+
+function MyApp() {
+  const app = useApp();
+
+  if (app.id !== APP_ID) {
+    throw new Error('Did not instantiate app client');
+  }
+
+  return (
+    <View>
+      <Text>Foo</Text>
+    </View>
+  );
+}
+// :remove-end:
+
+function AppWrapperLocal() {
+  const {RealmProvider} = RealmContext;
+
+  return (
+    <RealmProvider>
+      <MyApp />
+    </RealmProvider>
+  );
+}
+// :snippet-end:
+
+test('Instantiate RealmProvider correctly', () => {
+  render(<AppWrapperLocal />);
+});

examples/react-native/__tests__/ts/realm-database/configure-realm-multiple.test.tsx

@@ -0,0 +1,67 @@
+// :snippet-start: two-realm-contexts
+import React from 'react';
+import {AppProvider, UserProvider} from '@realm/react';
+import {RealmContext} from '../RealmConfig';
+import {SecondRealmContext} from '../RealmConfig';
+// :remove-start:
+import {render} from '@testing-library/react-native';
+import {useApp} from '@realm/react';
+import {View, Text} from 'react-native';
+
+const APP_ID = 'example-testers-kvjdy';
+
+function AppSectionOne() {
+  const app = useApp();
+
+  if (app.id !== APP_ID) {
+    throw new Error('Did not instantiate app client');
+  }
+
+  return (
+    <View>
+      <Text>Foo</Text>
+    </View>
+  );
+}
+
+function AppSectionTwo() {
+  const app = useApp();
+
+  if (app.id !== APP_ID) {
+    throw new Error('Did not instantiate app client');
+  }
+
+  return (
+    <View>
+      <Text>Bar</Text>
+    </View>
+  );
+}
+// :remove-end:
+
+function TwoRealmsWrapper() {
+  const {RealmProvider: RealmProvider} = RealmContext;
+  const {RealmProvider: SecondRealmProvider} = SecondRealmContext;
+
+  return (
+    <AppProvider id={APP_ID}>
+      <UserProvider>
+        {/* This realm uses Flexible Sync. */}
+        <RealmProvider 
+          sync={{flexible: true, onError: error => console.error(error)}}
+        >
+          <AppSectionOne />
+        </RealmProvider>
+        {/* This is a separate local-only realm. */}
+        <SecondRealmProvider>
+          <AppSectionTwo />
+        </SecondRealmProvider>
+      </UserProvider>
+    </AppProvider>
+  );
+}
+// :snippet-end:
+
+test('Instantiate SecondRealmProvider correctly', () => {
+  render(<TwoRealmsWrapper />);
+});

examples/react-native/__tests__/ts/realm-database/configure-realm-sync.test.tsx

@@ -0,0 +1,44 @@
+// :snippet-start: configure-realm-sync
+import React from 'react';
+import {AppProvider, UserProvider} from '@realm/react';
+import {RealmContext} from '../RealmConfig';
+// :remove-start:
+import {render} from '@testing-library/react-native';
+import {useApp} from '@realm/react';
+import {View, Text} from 'react-native';
+
+const APP_ID = 'example-testers-kvjdy';
+
+function MyApp() {
+  const app = useApp();
+
+  if (app.id !== APP_ID) {
+    throw new Error('Did not instantiate app client');
+  }
+
+  return (
+    <View>
+      <Text>Foo</Text>
+    </View>
+  );
+}
+// :remove-end:
+
+function AppWrapperSync() {
+  const {RealmProvider} = RealmContext;
+
+  return (
+    <AppProvider id={APP_ID}>
+      <UserProvider>
+        <RealmProvider sync={{flexible: true, onError: error => console.error(error)}}>
+          <MyApp />
+        </RealmProvider>
+      </UserProvider>
+    </AppProvider>
+  );
+}
+// :snippet-end:
+
+test('Instantiate RealmProvider correctly', () => {
+  render(<AppWrapperSync />);
+});

source/examples/generated/react-native/js/RealmConfig.snippet.create-realm-context.js

@@ -0,0 +1,9 @@
+import {createRealmContext} from '@realm/react';
+// Import all of your models.
+import Invoice from './Models/Invoice';
+import Business from './Models/Business';
+
+export const RealmContext = createRealmContext({
+  // Pass all of your models into the schema value.
+  schema: [Invoice, Business],
+});

source/examples/generated/react-native/js/RealmConfig.snippet.in-memory-realm.js

@@ -0,0 +1,4 @@
+export const InMemoryRealmContext = createRealmContext({
+  schema: [Address, Contact],
+  inMemory: true,
+});

source/examples/generated/react-native/ts/configure-realm-local.test.snippet.configure-realm.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import {RealmContext} from '../RealmConfig';
+
+function AppWrapperLocal() {
+  const {RealmProvider} = RealmContext;
+
+  return (
+    <RealmProvider>
+      <MyApp />
+    </RealmProvider>
+  );
+}

source/examples/generated/react-native/ts/configure-realm-multiple.test.snippet.two-realm-contexts.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import {AppProvider, UserProvider} from '@realm/react';
+import {RealmContext} from '../../RealmConfig';
+import {SecondRealmContext} from '../../RealmConfig';
+
+function TwoRealmsWrapper() {
+  const {RealmProvider: RealmProvider} = RealmContext;
+  const {RealmProvider: SecondRealmProvider} = SecondRealmContext;
+
+  return (
+    <AppProvider id={APP_ID}>
+      <UserProvider>
+        {/* This realm uses Flexible Sync. */}
+        <RealmProvider 
+          sync={{flexible: true, onError: error => console.error(error)}}
+        >
+          <AppSectionOne />
+        </RealmProvider>
+        {/* This is a separate local-only realm. */}
+        <SecondRealmProvider>
+          <AppSectionTwo />
+        </SecondRealmProvider>
+      </UserProvider>
+    </AppProvider>
+  );
+}

source/examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {AppProvider, UserProvider} from '@realm/react';
+import {RealmContext} from '../RealmConfig';
+
+function AppWrapperSync() {
+  const {RealmProvider} = RealmContext;
+
+  return (
+    <AppProvider id={APP_ID}>
+      <UserProvider>
+        <RealmProvider sync={{flexible: true, onError: error => console.error(error)}}>
+          <MyApp />
+        </RealmProvider>
+      </UserProvider>
+    </AppProvider>
+  );
+}

source/sdk/react-native.txt

@@ -102,7 +102,7 @@ clients.
              You can configure your realm to do things
              like populate initial data on load, be encrypted, and more.
              To begin working with your data,
-             :ref:`configure and open a realm <react-native-open-close-realm>`.
+             :ref:`configure and open a realm <react-native-configure-realm>`.
 
           .. step:: Read and Write Data
 

source/sdk/react-native/realm-database.txt

@@ -17,7 +17,7 @@ Realm Database - React Native SDK
    Define a Realm Object Model </sdk/react-native/realm-database/define-a-realm-object-model>
    Change an Object Model </sdk/react-native/realm-database/change-an-object-model>
    Schemas </sdk/react-native/realm-database/schemas/overview>
-   Open & Close a Realm </sdk/react-native/realm-database/open-and-close-a-realm>
+   Configure a Realm </sdk/react-native/realm-database/configure-a-realm>
    Write Transactions </sdk/react-native/realm-database/write-transactions>
    CRUD </sdk/react-native/realm-database/crud>
    React to Changes </sdk/react-native/realm-database/react-to-changes>

source/sdk/react-native/realm-database/bundle.txt

@@ -113,7 +113,7 @@ On a high level you:
       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 
       :js-sdk:`Realm.copyBundledRealmFiles() <Realm.html#.copyBundledRealmFiles>`
-      before you :ref:`open the realm <react-native-open-close-realm>`. 
+      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