Realm JS SDK

Realm is a mobile-first database designed to run directly on phones, tablets, or wearables. It provides a persistence layer for the Atlas Device SDKs. The JavaScript & TypeScript implementation supports:

• React Native (JSC & Hermes on iOS & Android)
• Node.js (Version 18 or later required)
• Electron (Windows, MacOS, and Linux)

Realm Web is designed for accessing Atlas App Services from a web browser. Note the following constraints:

• No Realm Sync: The realm-web package does not include a Realm Sync client. If you need Realm Sync, use the realm package in a Node.js, ReactNative, or Electron environment.
• Supported App Services: Currently, only a limited selection of App Services are implemented, specifically:
  • MongoDB: Read, write, and watch MongoDB documents.

Realm support is categorized into three tiers based on the package, version, and platform:

Tier 1 - fully supported

Timely responses during CET workdays, including bug fixes and new features.

• realm (NPM tag: latest) on node.js (active LTS) and Electron (Windows, MacOS, Linux).
• realm (NPM tag: latest) with React Native 0.71.0 (Android and iOS).
• @realm/react (NPM tag: latest) with the latest realm release.

Tier 2 - best effort

Support provided as time permits for mature/stable packages.

• realm-web (NPM tag: latest).
• Realm Studio (latest release) on Windows, MacOS, and Linux.
• Any other realm release not covered by Tier 1.

Tier 3 - experimental

Occasional work; packages are subject to radical changes.

• @realm/babel-plugin.

To run Google Sign-In tests, follow these steps:

1. Run the tests once to import a test app into your Atlas App Services server.
2. Note the assigned app id.
3. Navigate to the server's Admin UI and set up the Google Authentication Provider, ensuring "OpenID Connect" is toggled on.
4. Start the integration tests with DEV_TOOLS=1, providing your GOOGLE_CLIENT_ID and the BAAS_APP_ID.
5. After the tests complete, navigate the browser to http://localhost:8080/google-login and click "Sign in with Google" to complete the flow.

To view Node and V8 source code in stack traces instead of assembly, compile a custom debug version of Node.js. Note that debug symbol paths are hardcoded during compilation, so do not move the directory after building.

1. Download Node.js source code from https://nodejs.org/en/download/.
2. Unzip the source to your desired location.
3. From the Node source root, run ./configure --debug -C to enable debug mode and generate compile_commands.json for VS Code.
4. Run make -j32 to compile (adjust -j32 based on your CPU cores; 2x thread count is a common recommendation).

Navigate to the integration-tests directory to run the test suites.

Run all tests across all environments:

npm test

Run tests in watch mode (Development): Use this for rapid iteration. It runs Mocha in watch mode.

npm start

Run specific tests using grep: Use the --grep flag with a regular expression to match specific test titles.

npm start -- --grep "Realm#constructor"

To test your local changes to Realm JS, you can use these two sample projects:

React Native Sample

Clone the React Native sample project to test mobile changes:

git clone https://github.com/cesarvr/react-native-realm sample-rn-project
cd sample-rn-project
npm install

Node.js Sample

Clone the Node.js sample project to test Node environment changes:

git clone https://github.com/cesarvr/hello-world-realm-js hello-sync
cd hello-sync
npm install

If test suites fail to clean up resources, you can manually delete Atlas clusters and apps using the GitHub Actions workflow named Wipe all clusters and apps.

Warning: This workflow does not distinguish between active resources and leftover resources. Running this workflow while other tests are active may cause those running tests to fail.