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.
createRxDatabase
✓ import { createRxDatabase } from 'test-rxdb';
✗ const createRxDatabase = require('test-rxdb').createRxDatabase;
Since version 15, RxDB is primarily distributed as an ES Module. CommonJS users may need specific bundler configurations.
addRxPlugin
✓ import { addRxPlugin } from 'test-rxdb';
✗ const addRxPlugin = require('test-rxdb').addRxPlugin;
Used to extend RxDB's functionality with various plugins (e.g., replication, validation). This is typically imported directly from the main package.
getRxStorageDexie
✓ import { getRxStorageDexie } from 'test-rxdb/plugins/storage-dexie';
✗ import { getRxStorageDexie } from 'test-rxdb';
Storage adapters are crucial for RxDB and must be explicitly imported and provided during database creation. For the actual `rxdb` package, many storage adapters are separate npm packages (e.g., `rxdb-storage-dexie`) or part of `@rxdb/premium`. This example assumes a `test-rxdb/plugins/storage-dexie` path for demonstration.
RxDatabase
✓ import { RxDatabase, RxCollection, RxJsonSchema } from 'test-rxdb';
RxDB ships with comprehensive TypeScript types, which are directly importable from the main package for type annotations.
This quickstart demonstrates how to set up an RxDB database, define a schema, add a collection, insert documents, perform a reactive query, and update data using the Dexie storage adapter.
import { createRxDatabase, addRxPlugin, RxDatabase, RxCollection, RxJsonSchema } from 'test-rxdb';
import { getRxStorageDexie } from 'test-rxdb/plugins/storage-dexie'; // Assumed path for 'test-rxdb' package
interface HeroDocType {
name: string;
color: string;
hp: number;
maxHP: number;
}
type HeroCollection = RxCollection<HeroDocType>;
const heroSchema: RxJsonSchema<HeroDocType> = {
version: 0,
primaryKey: 'name',
type: 'object',
properties: {
name: {
type: 'string',
maxLength: 100 // Primary keys usually have a max length
},
color: {
type: 'string'
},
hp: {
type: 'number'
},
maxHP: {
type: 'number'
}
},
required: ['name', 'color', 'hp', 'maxHP']
};
async function runQuickstart() {
console.log('Creating database...');
const db: RxDatabase = await createRxDatabase({
name: 'heroesdb',
storage: getRxStorageDexie() // Using Dexie storage adapter
});
console.log('Database created:', db.name);
// Add a collection to the database
console.log('Adding hero collection...');
await db.addCollections({
heroes: {
schema: heroSchema
}
});
console.log('Hero collection added.');
const heroCollection: HeroCollection = db.collections.heroes;
// Insert documents
console.log('Inserting heroes...');
await heroCollection.insert({
name: 'Batman',
color: 'black',
hp: 100,
maxHP: 100
});
await heroCollection.insert({
name: 'Superman',
color: 'blue',
hp: 120,
maxHP: 120
});
console.log('Heroes inserted.');
// Reactive query: subscribe to changes in the collection
console.log('Subscribing to all heroes...');
const subscription = heroCollection.find().$.subscribe(heroes => {
if (heroes) {
console.log('Current heroes:', heroes.map(h => h.toJSON()));
}
});
// Update a document, which will trigger the subscription
console.log('Updating Batman...');
const batman = await heroCollection.findOne({ selector: { name: 'Batman' } }).exec();
if (batman) {
await batman.patch({ hp: 90 });
console.log('Batman updated.');
}
// Clean up after some time
setTimeout(() => {
subscription.unsubscribe();
console.log('Subscription unsubscribed.');
db.destroy(); // Close the database connection
console.log('Database destroyed (closed).');
}, 3000);
}
runQuickstart().catch(err => console.error('Quickstart failed:', err));
rxdb --version
Debug
Known issues
breakingRxDB v15+ is distributed as pure ES Modules (ESM). Projects using CommonJS (`require()`) must adapt their build setup (e.g., using a bundler with ESM support or configuring Node.js with `"type": "module"`).fixMigrate your project to use ES Modules or ensure your build tools (Webpack, Rollup, Parcel) are configured to handle ESM. For Node.js, ensure `"type": "module"` is set in your `package.json`.
affects: >=15.0.0
breakingThe storage API was completely rewritten in v15. Storage adapters must now be explicitly imported and passed to `createRxDatabase()` via the `storage` option. The old `storage.js` plugin and implicit storage handling are removed.fixRemove the `storage.js` plugin and explicitly import your chosen storage adapter (e.g., `getRxStorageDexie`) and provide it to `createRxDatabase({ storage: getRxStorageDexie() })`. Storage adapters are typically in separate packages like `rxdb-storage-dexie` or within `@rxdb/premium`. affects: >=15.0.0
breakingRxDB v15 no longer bundles `node:crypto` in browser builds. If your application relies on crypto functionalities (e.g., hashing), you might need to provide a polyfill for browser environments.fixFor browser-based applications, consider adding a polyfill for the Web Crypto API if your target environments do not fully support it, or provide a custom hash function if applicable.
affects: >=15.0.0
gotchaRxDB has a peer dependency on RxJS (`^7.8.0`). Ensure you have a compatible version of RxJS installed, as mismatches can lead to runtime errors or unexpected behavior.fixInstall `rxjs` explicitly: `npm install rxjs` or `yarn add rxjs`. Verify that the installed version meets RxDB's peer dependency requirements.
affects: >=15.0.0
deprecatedThe `LokiJS RxStorage` was deprecated in RxDB v15 and completely removed in v16, as the LokiJS library is no longer actively maintained.fixMigrate to a different storage adapter like Dexie.js, IndexedDB, or OPFS for browser environments, or Filesystem Node/SQLite for Node.js.
affects: >=15.0.0 <16.0.0
breakingThe `.destroy()` method has been renamed to `.close()` in RxDB v16 to better reflect its function of closing the database connection without deleting data.fixUpdate all calls from `db.destroy()` to `db.close()`. Also update related functions and attributes like `onDestroy()` to `onClose()`.
affects: >=16.0.0
Errors
Common errors & fixes
Error: Cannot find module 'test-rxdb/plugins/storage-dexie'
Attempting to import a storage adapter from an incorrect path or if the specific adapter is not included/exported by the `test-rxdb` package (or `rxdb` in general). In actual RxDB, many storages are separate npm packages.
fixVerify the correct import path for your chosen storage adapter. For official RxDB, you might need to install a separate package like `npm install rxdb-storage-dexie` and import from it: `import { getRxStorageDexie } from 'rxdb-storage-dexie';` TypeError: (0 , test_rxdb__WEBPACK_IMPORTED_MODULE_0__.createRxDatabase) is not a function
This typically occurs when mixing CommonJS `require()` with an ESM-only library, or due to a bundler misconfiguration preventing correct ESM resolution. RxDB v15+ is pure ESM.
fixEnsure your project is set up for ES Modules. Use `import { createRxDatabase } from 'test-rxdb';` and confirm your bundler/Node.js environment correctly processes ESM files. RxError: MvRx_NoRxStorageFound: Cannot create database, no storage set
This error means `createRxDatabase` was called without providing a storage adapter, which is mandatory in RxDB v15+.
fixExplicitly import and pass a storage adapter to the `storage` option when creating your database, e.g., `createRxDatabase({ name: 'mydb', storage: getRxStorageDexie() })`. RxError: UT8: Crypto.subtle.digest is not available in your runtime.
RxDB v15+ utilizes `crypto.subtle.digest` for hashing. This error indicates that the Web Crypto API is unavailable in the current runtime environment.
fixIf running in a browser, ensure it supports the Web Crypto API. For non-browser environments like some React Native setups or older Node.js versions, you may need to polyfill `crypto.subtle` or provide a custom hash function to RxDB.
Audit
Dependencies
rxjsrequiredRxDB's core reactivity and observable streams are built upon RxJS.