Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
/

Connect to an Atlas App Services Backend - Node.js SDK

On this page

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

The App client is the interface to the Atlas App Services backend. It provides access to the authentication functionality, functions, and sync management.

Before You Begin

  1. Create an App Services App

  2. Install the Realm Node.js SDK

Access the App Client

To connect to the App Services backend from your client, you need to create a configuration object. Then, pass that configuration object to a Realm.App() instance.

You must include the id field and the App ID for your App Services App, which you can find in the App Services UI.

// Initialize your App.
const app = new Realm.App({
  id: "<yourAppId>",
});

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.

Important

Changing an App Config After Initializing the App

Changed in version 12.6.0: baseUrl is not cached in the App configuration.

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

Retrieve an Instance of the App Client

To retrieve an instance of the App Client from anywhere in your application, call Realm.App.getApp() and pass in your App ID.

const app = Realm.App.getApp("<yourAppId>");

Configure a Timeout for the App Client

You can configure an optional timeout for requests in your AppConfiguration. It accepts a number of milliseconds before the request should timeout.

You can use this timeout interval with the optional Sync configuration cancelWaitsOnNonFatalErrors boolean. When the timeout interval elapses, any outstanding work that is awaiting uploads and downloads cancels. When this setting is false, awaiting uploads and downloads does not cancel because Realm treats these timeouts as non-fatal errors.

For an example, refer to Cancel Asynchronous Operations after a Timeout.

const app = new Realm.App({
  id: APP_ID,
  // You can optionally specify a timeout in milliseconds
  timeout: 10000,
});

Encrypt App Metadata

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:

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

Connect to a Specific Server

By default, Atlas Device SDK connects to Atlas using the global baseURL of https://services.cloud.mongodb.com. In some cases, you may want to connect to a different server:

You can specify a baseURL in the AppConfiguration:

Connect to a Different Server During Runtime

New in version 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.

To change the baseURL during runtime, call the app.updateBaseUrl() method. Note that the string value can't end in a trailing slash.

This API is experimental, so you must use the experimental import in the file where you want to use this API:

import "realm/experimental/base-url";

TypeScript Config for Experimental API

The app.updateBaseUrl() method is in an experimental module that you must import separately. To get the proper types from this module, you need to set the following fields in your tsconfig.json file:

{
   "target": "es2022",
   "module": "node16",
   "moduleResolution": "node16",
   // ...
}

Change Server with Logged-in User

If you want to change the baseURL after you have logged in a user and have opened a synced database, the app must perform a client reset. Perform these steps in your code:

  1. Pause the Sync session.

  2. Update the baseURL by calling the app.updateBaseUrl() method.

  3. Go through the authentication flow again to log in the user through the new baseURL.

  4. Open a synced database pulling data from the new server.

Both the server and the client must be online for the user to authenticate and connect to the new server. If the server is not online or the client does not have a network connection, the user cannot authenticate and open the database.

← 
 →

On this page