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.
createRxServer
✓ import { createRxServer } from 'rxdb-server/plugins/server';
✗ import { createRxServer } from 'rxdb-server';
The primary function to create an RxDB server is a named export from a specific plugin path.
RxServerAdapterExpress
✓ import { RxServerAdapterExpress } from 'rxdb-server/plugins/adapter-express';
✗ import { RxServerAdapterExpress } from 'rxdb-server/adapters/express';
Adapter plugins, like the Express adapter, are imported from their respective plugin paths. Ensure `express` is also installed as a dependency.
addReplicationEndpoint
✓ const myServer = await createRxServer(...);
myServer.addReplicationEndpoint(...);
This is a method called on an `RxServer` instance, not a direct export. It's crucial for setting up data synchronization.
This quickstart demonstrates setting up an in-memory RxDB, creating an RxDB server with Express adapter, and exposing replication and REST endpoints.
import { createRxDatabase, addRxPlugin } from 'rxdb';
import { getRxStorageMemory } from 'rxdb/plugins/storage-memory';
import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode';
import { createRxServer } from 'rxdb-server/plugins/server';
import { RxServerAdapterExpress } from 'rxdb-server/plugins/adapter-express';
const runServer = async () => {
// Enable dev mode for helpful warnings in development
addRxPlugin(RxDBDevModePlugin);
// Define a simple schema for our data
const mySchema = {
version: 0,
primaryKey: 'id',
type: 'object',
properties: {
id: { type: 'string', maxLength: 100 },
name: { type: 'string', maxLength: 100 },
age: { type: 'number' }
},
required: ['id', 'name']
};
// Create a RxDB database in memory for demonstration
const db = await createRxDatabase({
name: 'heroesdb',
storage: getRxStorageMemory()
});
// Add a collection
const heroesCollection = await db.addCollections({
heroes: { schema: mySchema }
});
// Insert some initial data
await heroesCollection.heroes.insert({
id: 'hero1',
name: 'SuperMan',
age: 40
});
console.log('Initial data inserted into RxDB.');
// Create the RxDB Server
const rxdbServer = await createRxServer({
database: db,
adapter: RxServerAdapterExpress,
port: 3000,
cors: true
});
// Add a replication endpoint for the 'heroes' collection
await rxdbServer.addReplicationEndpoint({
name: 'heroes-replication',
collection: heroesCollection.heroes
});
// Add a REST endpoint for basic CRUD operations
await rxdbServer.addRESTEndpoint({
name: 'heroes-rest',
collection: heroesCollection.heroes
});
// Start the server
await rxdbServer.start();
console.log('RxDB Server started on http://localhost:3000');
console.log('Replication endpoint: http://localhost:3000/heroes-replication/0');
console.log('REST endpoint (query): POST http://localhost:3000/heroes-rest/query');
};
runServer().catch(err => console.error('Error starting server:', err));
Debug
Known issues
breakingThe `rxdb-server` package uses the Server Side Public License (SSPL). This license restricts cloud providers from offering SSPL-licensed software as a service without a commercial license. Users should be aware of these legal implications, especially for commercial deployments where the software is offered as a service. [cite: README]fixReview the SSPL license terms carefully (https://en.wikipedia.org/wiki/Server_Side_Public_License) or consult legal counsel if you plan to offer services based on `rxdb-server`.
affects: >=1.0.0
gotchaIssues for `rxdb-server` are managed in the main `RxDB` repository. Users encountering bugs or seeking features should open issues there, not in the `rxdb-server` repository itself. [cite: README]fixReport issues on the main RxDB GitHub repository: `https://github.com/pubkey/rxdb/issues`.
affects: >=1.0.0
breakingSince RxDB v9.0.0, all default exports were removed from the `rxdb` package and its plugins to improve tree-shaking. Imports must now use named exports, e.g., `import { createRxDatabase } from 'rxdb';`. This affects any code interacting with the core `rxdb` library, which is a peer dependency of `rxdb-server`.fixUpdate all `import` statements from `import RxDB from 'rxdb'` to use named imports like `import { createRxDatabase, addRxPlugin } from 'rxdb';`. Similarly, plugins require specific named imports. affects: >=9.0.0 (for rxdb)
gotchaWhen defining schemas for RxDB collections used with `rxdb-server`, special consideration is needed for `serverOnlyFields` and `internalIndexes`. These fields might require different schema definitions on the server compared to clients to optimize server queries or hide sensitive data from clients.fixUtilize `serverOnlyFields` for fields that should only exist on the server and `internalIndexes` for indexes without the `_deleted` field, especially for server-side queries. Ensure your client-side schemas are adjusted accordingly, typically by omitting `serverOnlyFields`.
affects: >=1.0.0
gotchaUsing `rxdb-server` (or RxDB itself) in environments with bundlers like Webpack (e.g., in Angular projects) might lead to `Uncaught ReferenceError: global is not defined`. This occurs because some RxDB dependencies expect Node.js-specific global variables.fixManually polyfill the `global` and `process` variables in your environment entry file (e.g., `polyfills.ts` for Angular, or at the top of your main server file): `(global as any).global = global; (global as any).process = { env: { DEBUG: undefined } };` affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'addCollections')
The RxDB database instance was not properly created or initialized before attempting to add collections.
fixEnsure `createRxDatabase` is awaited and returns a valid database object before calling `db.addCollections()`.
Error: Peer dependency 'rxdb' is not installed or mismatched version.
The `rxdb` package, a required peer dependency, is either missing or its version does not satisfy the `rxdb-server` requirements.
fixInstall `rxdb` using `npm install rxdb` and ensure its version is compatible with `rxdb-server`. Check `npm view rxdb-server peerDependencies` for exact version ranges.
Error: RxDB storage is not set. Add a storage like 'getRxStorageMemory()' to the database options.
The `createRxDatabase` function was called without a specified RxStorage plugin, which is mandatory for RxDB operation.
fixImport and provide a suitable storage plugin, e.g., `getRxStorageMemory()` for in-memory, `getRxStorageDexie()` for IndexedDB in browsers, or specific Node.js storages. Example: `storage: getRxStorageMemory()`.
Audit
Dependencies
rxdbrequiredCore reactive database library that rxdb-server extends and operates on.
rxjsrequiredReactive programming library, a core dependency for RxDB's reactive features.