Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Connect to an Atlas App Services App - React Native SDK

On this page

  • Before You Begin
  • Configure the App Client
  • Retrieve an Instance of the App Client
  • Retrieve App Outside the App Provider
  • Encrypt App Metadata
  • Connect to a Specific Server
  • Connect to a Different Server During Runtime

The App client is the interface to the App Services backend. It provides access to the authentication functionality, Atlas Functions, and Atlas Device Sync.

  1. Create an App Services App

  2. Get Your App ID

To set up your App client, pass the App ID string to the id prop of the AppProvider. Wrap any components that need to access the App with the AppProvider. In this example, we wrap the UserProvider in the AppProvider to authenticate a user.

import React from 'react';
import {AppProvider, UserProvider} from '@realm/react';
export const AppWithAuthHook = () => {
return (
<AppProvider id={APP_ID}>
<UserProvider fallback={LogIn}>
<MyApp />

You can create multiple App client instances to connect to multiple Apps. All App client instances that share the same App ID use the same underlying connection.


Changing an App Config After Initializing the App

Changed in version realm@12.6.0: baseUrl is not cached

When you initialize the App client, the configuration is cached internally. Attempting to "close" and then re-open an App with a changed configuration within the same process has no effect. The client continues to use the cached configuration.

Starting with React Native SDK version 12.6.0, the baseUrl in the AppConfiguration is not cached. This means that you can change the baseUrl and the App client will use the updated configuration. In earlier SDK versions, changes to the baseUrl in a cached App configuration have no effect.

All components wrapped within an AppProvider can access the App client with the useApp() hook.

import React from 'react';
import {useApp} from '@realm/react';
function MyApp() {
const app = useApp();
// Proceed to app logic...

To retrieve an instance of the App Client from anywhere in your application, instantiate a new instance of Realm.App() from the realm package, then pass in your App ID.

import Realm from 'realm';
const app = Realm.App.getApp("<Your App ID>");

You can encrypt the metadata that App Services stores on client devices. Use the values of the MetadataMode enum to determine encryption behavior.

To encrypt App metadata:

  1. Import MetadataMode from Realm and import other dependencies:

    import React from 'react';
    import {Text, View} from 'react-native';
    import {MetadataMode} from 'realm';
    import {AppProvider} from '@realm/react';
  2. Create an App configuration object that contains the metadata property.

  3. Set metadata.mode to MetadataMode.Encryption.

  4. Set metadata.encryptionKey to the key you want to use for encryption.

  5. Pass the App configuration object to new Realm.App().

const EncryptMetadata = ({
}: {
encryptionKey: ArrayBuffer;
}) => {
const metadataConfig = {
mode: MetadataMode.Encryption,
encryptionKey: encryptionKey,
return (
<RestOfApp />

By default, Atlas Device SDK connects to Atlas using the global baseURL of In some cases, you may want to connect to a different server:

You can specify a baseURL as a prop for AppProvider. All AppConfiguration keys can be passed as props to AppProvider.

Changed in version realm@12.8.0.

In some cases, you might want to change the baseURL while the app is running. For example, you might want to roam between Edge Servers, or move from an App Services connection to an Edge Server connection.

Currently, this feature is implemented as an experimental module that requires specific TypeScript configuration. The required configuration can be difficult to make work with a React Native app. For more information on implementation, refer to documentation for the Node.js SDK.

← Atlas App Services