Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Realm
✓ import Realm from 'realm';
✗ const Realm = require('realm');
The primary class for opening, configuring, and interacting with a Realm database. CommonJS `require` is generally not recommended for modern Node.js or React Native development, especially with type-checking.
Configuration
✓ import type { Configuration } from 'realm';
Imports the TypeScript type for Realm configuration options. While often inferred, explicit typing is good practice, especially in large codebases.
ObjectSchema
✓ import type { ObjectSchema } from 'realm';
Imports the TypeScript type for defining the schema of Realm objects. Used in the `schema` array of the Realm configuration for type safety and clarity.
Initializes a Realm database, defines object schemas, performs write operations (creation and update), and queries existing data. It demonstrates basic CRUD.
import Realm from 'realm';
// Define your schema (object models)
class Car extends Realm.Object {
static schema = {
name: 'Car',
properties: {
make: 'string',
model: 'string',
miles: { type: 'int', default: 0 },
},
};
}
class Person extends Realm.Object {
static schema = {
name: 'Person',
properties: {
name: 'string',
cars: 'Car[]', // Define a relationship
},
};
}
// Open a realm with the defined schemas
async function runRealmExample() {
try {
const realm = await Realm.open({
path: 'myrealm.realm',
schema: [Car, Person],
schemaVersion: 1,
// Exclude from iCloud backup, useful for app-specific data that can be re-downloaded
excludeFromIcloudBackup: process.env.NODE_ENV === 'production' ? true : false,
});
// Write to the realm within a transaction
realm.write(() => {
const myCar = realm.create('Car', { make: 'Honda', model: 'Civic', miles: 1000 });
realm.create('Person', { name: 'Alice', cars: [myCar] });
realm.create('Car', { make: 'Toyota', model: 'Camry', miles: 5000 });
});
// Query objects
const cars = realm.objects('Car');
console.log(`Total cars in the realm: ${cars.length}`);
const hondas = cars.filtered('make == "Honda"');
console.log(`Number of Hondas: ${hondas.length}`);
// Update an object
realm.write(() => {
const civic = hondas[0];
if (civic) {
civic.miles += 500;
}
});
console.log(`Honda Civic miles after update: ${hondas[0]?.miles}`);
// Remember to close the realm when done to release resources
realm.close();
} catch (error) {
console.error("Error opening or interacting with Realm:", error);
}
}
runRealmExample();
realm --version
Debug
Known issues
breakingAtlas Device Sync functionality has been completely removed from Realm JS starting with v20.0.0. Applications relying on Device Sync will break and need to migrate to an alternative synchronization solution or use a pre-v20 version, understanding its limitations.fixRemove all Device Sync related code. If sync is required, explore other MongoDB Atlas App Services or alternative sync mechanisms. A separate 'community' package might be available for sync-less legacy projects.
affects: >=20.0.0
breakingRealm JS v20.2.0 and v12.15.0 (and subsequent versions in these lines) do not support the deprecated legacy architecture of React Native. This impacts older React Native projects.fixUpgrade your React Native project to the New Architecture (TurboModules/Fabric), or stick to older Realm JS versions (e.g., <v12.15.0 or <v20.2.0) if migration is not immediately feasible.
affects: >=12.15.0, >=20.2.0
gotchaSetting `List` values from themselves (e.g., `myObject.myList = myObject.myList`) could lead to unexpected emptying of the list due to an internal iteration bug.fixUpgrade to Realm JavaScript v12.14.2 or later to receive the fix for this specific `List` assignment behavior.
affects: >=12.12.0 <12.14.2
gotchaClosing and re-opening a synced realm before a token refresh completes could result in a crash with a 'MultipleSyncAgents' exception.fixUpgrade to Realm JavaScript v12.14.1 or later. Ensure proper handling of realm closure and opening, especially in environments with active sync (though sync is deprecated in v20+).
affects: >=12.0.0 <12.14.1 (for synced realms)
gotchaThe `excludeFromIcloudBackup` option was added to the `Realm` constructor to control whether realm files are included in iCloud backups on iOS. The default is `false` (included).fixSet `excludeFromIcloudBackup: true` in your `Realm.open` configuration if you wish to prevent realm files from being backed up to iCloud, which is often a requirement for user-generated content that can be re-downloaded.
affects: >=12.14.0, >=20.1.0
gotchaMigrating a primary key to a new type without providing a migration function would cause an assertion to fail during schema migration.fixUpgrade to Realm JavaScript v12.14.1 or later. When changing the type of a primary key in a schema, always provide a migration function to handle the data transformation explicitly.
affects: >=12.0.0 <12.14.1
Errors
Common errors & fixes
Error opening or interacting with Realm: MultipleSyncAgents exception
Attempting to open a synchronized realm multiple times concurrently, often due to closing and reopening while a token refresh is in progress. (Applies to pre-v20 sync enabled versions)
fixUpgrade to Realm JS v12.14.1 or newer. For v20+, sync features are removed, making this error specific to older versions. Ensure careful lifecycle management of Realm instances.
Assertion failed: (key_type.has_primary_key()) && (new_key_type.has_primary_key())
Attempting to migrate a primary key field to a new type within a schema update without defining a migration function to handle the data transformation.
fixUpgrade to Realm JS v12.14.1 or newer. When performing schema migrations that alter primary key types, ensure a comprehensive migration function is provided to correctly transform or re-index the data.
Failed to install the app. Make sure you have the Android SDK installed and configured correctly. (or similar build error on React Native Android)
Build errors on React Native Android, particularly for React Native 0.76 due to changes in dynamic library merging or general native module linking issues.
fixUpgrade to Realm JS v12.13.2 or later, which includes fixes for build errors on React Native Android when used with React Native 0.76 and newer. Also, try cleaning your Android build cache (`cd android && ./gradlew clean && cd ..`) and re-installing node modules.
Invariant Violation: 'RCTBridgeModule' required for native module 'Realm' is null.
Common issue in React Native when the native module for Realm isn't correctly linked or initialized, often after an upgrade, cache corruption, or incorrect auto-linking.
fixFor React Native, try `npx react-native start --reset-cache`, then `cd ios && pod install && cd ..`. Ensure your `Podfile` for iOS has `use_frameworks!` if needed. Verify compatibility with your `react-native` version and ensure auto-linking is functioning correctly (e.g., check `react-native config`).
Audit
Dependencies
react-nativeoptionalRequired for React Native projects, specifies minimum compatible version for integration.