{"id":16516,"library":"realm","title":"Realm Database for JavaScript","description":"Realm JS is an offline-first, mobile-optimized database designed for JavaScript environments including React Native, Node.js, and Electron. It provides direct access to data as native JavaScript objects, eliminating the need for ORMs and offering performance often surpassing raw SQLite operations. The current stable major version is v20.x, with v20.2.0 being a recent release. Realm maintains a frequent release cadence, often with minor updates and bug fixes. A key differentiator was its integration with MongoDB Atlas Device Sync, but this feature was officially deprecated and removed starting with v20.0.0. Developers now using `realm` (v20+) should treat it as a robust local-only database, with a separate `community` package available for the sync-less version.","status":"active","version":"20.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/realm/realm-js","tags":["javascript","database","db","storage","react","react-native","persistence","local storage","localstorage","typescript"],"install":[{"cmd":"npm install realm","lang":"bash","label":"npm"},{"cmd":"yarn add realm","lang":"bash","label":"yarn"},{"cmd":"pnpm add realm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for React Native projects, specifies minimum compatible version for integration.","package":"react-native","optional":true}],"imports":[{"note":"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.","wrong":"const Realm = require('realm');","symbol":"Realm","correct":"import Realm from 'realm';"},{"note":"Imports the TypeScript type for Realm configuration options. While often inferred, explicit typing is good practice, especially in large codebases.","symbol":"Configuration","correct":"import type { Configuration } from 'realm';"},{"note":"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.","symbol":"ObjectSchema","correct":"import type { ObjectSchema } from 'realm';"}],"quickstart":{"code":"import Realm from 'realm';\n\n// Define your schema (object models)\nclass Car extends Realm.Object {\n  static schema = {\n    name: 'Car',\n    properties: {\n      make: 'string',\n      model: 'string',\n      miles: { type: 'int', default: 0 },\n    },\n  };\n}\n\nclass Person extends Realm.Object {\n  static schema = {\n    name: 'Person',\n    properties: {\n      name: 'string',\n      cars: 'Car[]', // Define a relationship\n    },\n  };\n}\n\n// Open a realm with the defined schemas\nasync function runRealmExample() {\n  try {\n    const realm = await Realm.open({\n      path: 'myrealm.realm',\n      schema: [Car, Person],\n      schemaVersion: 1,\n      // Exclude from iCloud backup, useful for app-specific data that can be re-downloaded\n      excludeFromIcloudBackup: process.env.NODE_ENV === 'production' ? true : false,\n    });\n\n    // Write to the realm within a transaction\n    realm.write(() => {\n      const myCar = realm.create('Car', { make: 'Honda', model: 'Civic', miles: 1000 });\n      realm.create('Person', { name: 'Alice', cars: [myCar] });\n      realm.create('Car', { make: 'Toyota', model: 'Camry', miles: 5000 });\n    });\n\n    // Query objects\n    const cars = realm.objects('Car');\n    console.log(`Total cars in the realm: ${cars.length}`);\n    const hondas = cars.filtered('make == \"Honda\"');\n    console.log(`Number of Hondas: ${hondas.length}`);\n\n    // Update an object\n    realm.write(() => {\n      const civic = hondas[0];\n      if (civic) {\n        civic.miles += 500;\n      }\n    });\n    console.log(`Honda Civic miles after update: ${hondas[0]?.miles}`);\n\n    // Remember to close the realm when done to release resources\n    realm.close();\n  } catch (error) {\n    console.error(\"Error opening or interacting with Realm:\", error);\n  }\n}\n\nrunRealmExample();","lang":"typescript","description":"Initializes a Realm database, defines object schemas, performs write operations (creation and update), and queries existing data. It demonstrates basic CRUD."},"warnings":[{"fix":"Remove 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.","message":"Atlas 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.","severity":"breaking","affected_versions":">=20.0.0"},{"fix":"Upgrade 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.","message":"Realm 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.","severity":"breaking","affected_versions":">=12.15.0, >=20.2.0"},{"fix":"Upgrade to Realm JavaScript v12.14.2 or later to receive the fix for this specific `List` assignment behavior.","message":"Setting `List` values from themselves (e.g., `myObject.myList = myObject.myList`) could lead to unexpected emptying of the list due to an internal iteration bug.","severity":"gotcha","affected_versions":">=12.12.0 <12.14.2"},{"fix":"Upgrade 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+).","message":"Closing and re-opening a synced realm before a token refresh completes could result in a crash with a 'MultipleSyncAgents' exception.","severity":"gotcha","affected_versions":">=12.0.0 <12.14.1 (for synced realms)"},{"fix":"Set `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.","message":"The `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).","severity":"gotcha","affected_versions":">=12.14.0, >=20.1.0"},{"fix":"Upgrade 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.","message":"Migrating a primary key to a new type without providing a migration function would cause an assertion to fail during schema migration.","severity":"gotcha","affected_versions":">=12.0.0 <12.14.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade 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.","cause":"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)","error":"Error opening or interacting with Realm: MultipleSyncAgents exception"},{"fix":"Upgrade 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.","cause":"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.","error":"Assertion failed: (key_type.has_primary_key()) && (new_key_type.has_primary_key())"},{"fix":"Upgrade 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.","cause":"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.","error":"Failed to install the app. Make sure you have the Android SDK installed and configured correctly. (or similar build error on React Native Android)"},{"fix":"For 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`).","cause":"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.","error":"Invariant Violation: 'RCTBridgeModule' required for native module 'Realm' is null."}],"ecosystem":"npm"}