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

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.

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:

   JavaScript

   TypeScript

   import Realm, { BSON, MetadataMode } from "realm";

   import Realm, {
     AppConfiguration,
     BSON,
     MetadataMode,
     Configuration,
   } from "realm";

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

// Retrieve encryption key from secure location or create one
const encryptionKey = new ArrayBuffer(64);
// Use encryption key in app configuration
const config = {
  id: APP_ID,
  metadata: { mode: MetadataMode.Encryption, encryptionKey: encryptionKey },
};
const app = new Realm.App(config);

// Retrieve encryption key from secure location or create one
const encryptionKey = new ArrayBuffer(64);
// Use encryption key in app configuration
const config: AppConfiguration = {
  id: APP_ID,
  metadata: { mode: MetadataMode.Encryption, encryptionKey: encryptionKey },
};
const app = new Realm.App(config);

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:

• Your App Services App uses local deployment, and you want to connect directly to a local baseURL in your region.

• You want to connect to an Edge Server instance.

You can specify a baseURL in the AppConfiguration:

.. code-block:: javascript
   const appConfig = {
     id: APP_ID,
     baseUrl: "https://example.com",
   };
   const app = new App(appConfig);

.. code-block:: typescript
   const appConfig: AppConfiguration = {
     id: APP_ID,
     baseUrl: "https://example.com",
   };
   const app = new App(appConfig);

const app = new App(EDGE_APP_ID);
await app.updateBaseUrl("http://localhost:80");
// ... log in a user and use the app...
// ... some time later...
// Reset baseURL to the default: https://services.cloud.mongodb.com
await app.updateBaseUrl(null);

const app = new App(EDGE_APP_ID);
await app.updateBaseUrl("http://localhost:80");
// ... log in a user and use the app...
// ... some time later...
// Reset baseURL to the default: https://services.cloud.mongodb.com
await app.updateBaseUrl(null);

import "realm/experimental/base-url";

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