{"id":11970,"library":"rxdb-server","title":"RxDB Server","description":"RxDB Server is a plugin for the RxDB (Reactive Database) ecosystem, enabling server-side capabilities for RxDB databases. It allows users to spawn a server on top of an RxDB instance, providing various endpoints such as CRUD REST APIs and real-time replication endpoints. This facilitates data synchronization between client devices and the server, supporting offline-first architectures and real-time data updates. The package is designed for Node.js, Deno, Bun, or Electron's main process and can operate as a standalone server or integrate with existing HTTP frameworks like Express. Currently at version 17.1.0, it generally follows the release cadence of the main RxDB library. A key differentiator is its Server Side Public License (SSPL), similar to MongoDB's, which aims to prevent large cloud vendors from monetizing the software without contributing back. The plugin is maintained separately from the core RxDB due to its specific dependencies and licensing model.","status":"active","version":"17.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/pubkey/rxdb-server","tags":["javascript","rxdb","server","typescript"],"install":[{"cmd":"npm install rxdb-server","lang":"bash","label":"npm"},{"cmd":"yarn add rxdb-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add rxdb-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core reactive database library that rxdb-server extends and operates on.","package":"rxdb","optional":false},{"reason":"Reactive programming library, a core dependency for RxDB's reactive features.","package":"rxjs","optional":false}],"imports":[{"note":"The primary function to create an RxDB server is a named export from a specific plugin path.","wrong":"import { createRxServer } from 'rxdb-server';","symbol":"createRxServer","correct":"import { createRxServer } from 'rxdb-server/plugins/server';"},{"note":"Adapter plugins, like the Express adapter, are imported from their respective plugin paths. Ensure `express` is also installed as a dependency.","wrong":"import { RxServerAdapterExpress } from 'rxdb-server/adapters/express';","symbol":"RxServerAdapterExpress","correct":"import { RxServerAdapterExpress } from 'rxdb-server/plugins/adapter-express';"},{"note":"This is a method called on an `RxServer` instance, not a direct export. It's crucial for setting up data synchronization.","symbol":"addReplicationEndpoint","correct":"const myServer = await createRxServer(...);\nmyServer.addReplicationEndpoint(...);"}],"quickstart":{"code":"import { createRxDatabase, addRxPlugin } from 'rxdb';\nimport { getRxStorageMemory } from 'rxdb/plugins/storage-memory';\nimport { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode';\nimport { createRxServer } from 'rxdb-server/plugins/server';\nimport { RxServerAdapterExpress } from 'rxdb-server/plugins/adapter-express';\n\nconst runServer = async () => {\n  // Enable dev mode for helpful warnings in development\n  addRxPlugin(RxDBDevModePlugin);\n\n  // Define a simple schema for our data\n  const mySchema = {\n    version: 0,\n    primaryKey: 'id',\n    type: 'object',\n    properties: {\n      id: { type: 'string', maxLength: 100 },\n      name: { type: 'string', maxLength: 100 },\n      age: { type: 'number' }\n    },\n    required: ['id', 'name']\n  };\n\n  // Create a RxDB database in memory for demonstration\n  const db = await createRxDatabase({\n    name: 'heroesdb',\n    storage: getRxStorageMemory()\n  });\n\n  // Add a collection\n  const heroesCollection = await db.addCollections({\n    heroes: { schema: mySchema }\n  });\n\n  // Insert some initial data\n  await heroesCollection.heroes.insert({\n    id: 'hero1',\n    name: 'SuperMan',\n    age: 40\n  });\n  console.log('Initial data inserted into RxDB.');\n\n  // Create the RxDB Server\n  const rxdbServer = await createRxServer({\n    database: db,\n    adapter: RxServerAdapterExpress,\n    port: 3000,\n    cors: true\n  });\n\n  // Add a replication endpoint for the 'heroes' collection\n  await rxdbServer.addReplicationEndpoint({\n    name: 'heroes-replication',\n    collection: heroesCollection.heroes\n  });\n\n  // Add a REST endpoint for basic CRUD operations\n  await rxdbServer.addRESTEndpoint({\n    name: 'heroes-rest',\n    collection: heroesCollection.heroes\n  });\n\n  // Start the server\n  await rxdbServer.start();\n  console.log('RxDB Server started on http://localhost:3000');\n  console.log('Replication endpoint: http://localhost:3000/heroes-replication/0');\n  console.log('REST endpoint (query): POST http://localhost:3000/heroes-rest/query');\n};\n\nrunServer().catch(err => console.error('Error starting server:', err));","lang":"typescript","description":"This quickstart demonstrates setting up an in-memory RxDB, creating an RxDB server with Express adapter, and exposing replication and REST endpoints."},"warnings":[{"fix":"Review 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`.","message":"The `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]","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Report issues on the main RxDB GitHub repository: `https://github.com/pubkey/rxdb/issues`.","message":"Issues 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]","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update all `import` statements from `import RxDB from 'rxdb'` to use named imports like `import { createRxDatabase, addRxPlugin } from 'rxdb';`. Similarly, plugins require specific named imports.","message":"Since 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`.","severity":"breaking","affected_versions":">=9.0.0 (for rxdb)"},{"fix":"Utilize `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`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Manually 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 } };`","message":"Using `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `createRxDatabase` is awaited and returns a valid database object before calling `db.addCollections()`.","cause":"The RxDB database instance was not properly created or initialized before attempting to add collections.","error":"TypeError: Cannot read properties of undefined (reading 'addCollections')"},{"fix":"Install `rxdb` using `npm install rxdb` and ensure its version is compatible with `rxdb-server`. Check `npm view rxdb-server peerDependencies` for exact version ranges.","cause":"The `rxdb` package, a required peer dependency, is either missing or its version does not satisfy the `rxdb-server` requirements.","error":"Error: Peer dependency 'rxdb' is not installed or mismatched version."},{"fix":"Import 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()`.","cause":"The `createRxDatabase` function was called without a specified RxStorage plugin, which is mandatory for RxDB operation.","error":"Error: RxDB storage is not set. Add a storage like 'getRxStorageMemory()' to the database options."}],"ecosystem":"npm"}