From 486a1826b91c81342444fe8fa0a6957988f129b7 Mon Sep 17 00:00:00 2001 From: pubkey <8926560+pubkey@users.noreply.github.com> Date: Thu, 22 Jan 2026 13:58:25 +0100 Subject: [PATCH 1/5] ADD RxDB Tanstack FAQ --- docs/collections/rxdb-collection.md | 35 ++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/collections/rxdb-collection.md b/docs/collections/rxdb-collection.md index 71ea3ffed..148cf00ad 100644 --- a/docs/collections/rxdb-collection.md +++ b/docs/collections/rxdb-collection.md @@ -22,7 +22,7 @@ The `@tanstack/rxdb-db-collection` package allows you to create collections that ## 1. Installation -Install the RXDB collection packages along with your preferred framework integration. +Install the RxDB collection packages along with your preferred framework integration. ```bash npm install @tanstack/rxdb-db-collection rxdb @tanstack/react-db @@ -132,3 +132,36 @@ Replication and sync in RxDB run independently of TanStack DB. You set up replic When replication runs, it pulls and pushes changes to the backend and applies them to the RxDB collection. Since the TanStack DB integration subscribes to the RxDB change stream, any changes applied by replication are automatically reflected in your TanStack DB collection. This separation of concerns means you configure replication entirely in RxDB, and TanStack DB automatically benefits: your TanStack collections always stay up to date with whatever sync strategy you choose. + + +## FAQ + +### Do I still need RxDB schema indexes if I only query TanStack DB? + +Usually not for TanStack DB queries themselves. TanStack DB queries run entirely in memory, so RxDB schema indexes do not affect the performance of TanStack DB's live queries. However, RxDB indexes may still be important if: +- You run queries directly against RxDB (e.g. `rxCollection.find(...)`). +- Your replication setup uses filtered queries or selectors. +- You rely on RxDB to selectively load subsets of data instead of hydrating everything into memory. + +### Is data duplicated between RxDB and TanStack DB? + +Yes, intentionally. RxDB stores data durably on disk. TanStack DB stores data in memory for fast queries and reactivity. This duplication enables high-performance UI queries while retaining [local-first](https://rxdb.info/articles/local-first-future.html) persistence and sync. + +### How does backend ↔ RxDB ↔ TanStack DB synchronization work? + +Synchronization follows a clear separation of responsibilities between RxDB and TanStack DB. + +**RxDB** is responsible for persistence and networking. It stores data durably using a local storage engine (IndexedDB, SQLite, etc.) and handles all replication logic. Replication is configured directly on the RxDB collection and runs independently of TanStack DB. RxDB pulls changes from the backend, applies them locally, resolves conflicts, and pushes local changes back to the backend. + +**TanStack DB** sits on top as an in-memory, reactive query layer. It does not talk to the backend directly and does not participate in replication. Instead, it mirrors the current state of the RxDB collection in memory and provides fast live queries and optimistic mutations for the UI. + +This design intentionally forms two independent loops: +- A durability and sync loop managed entirely by RxDB (backend to RxDB). +- A reactive UI loop managed by TanStack DB (RxDB change stream to in-memory collections to live queries). + +## Learn More + +- [RxDB Documentation](https://rxdb.info/overview.html) +- [RxDB Sync Engine](https://rxdb.info/replication.html) +- [Tanstack DB Live Queries](https://tanstack.com/db/latest/docs/guides/live-queries) + From 199a72770bf4e98b847dc9289afcbc2d3479681d Mon Sep 17 00:00:00 2001 From: pubkey <8926560+pubkey@users.noreply.github.com> Date: Thu, 22 Jan 2026 14:02:18 +0100 Subject: [PATCH 2/5] FIX typos --- docs/collections/rxdb-collection.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/collections/rxdb-collection.md b/docs/collections/rxdb-collection.md index 148cf00ad..d139ddc7f 100644 --- a/docs/collections/rxdb-collection.md +++ b/docs/collections/rxdb-collection.md @@ -20,7 +20,7 @@ The `@tanstack/rxdb-db-collection` package allows you to create collections that - Leverage RxDB's [replication plugins](https://rxdb.info/replication.html) to sync with CouchDB, MongoDB, Supabase, REST APIs, GraphQL, WebRTC (P2P) and more. -## 1. Installation +### 1. Installation Install the RxDB collection packages along with your preferred framework integration. @@ -35,8 +35,8 @@ npm install @tanstack/rxdb-db-collection rxdb @tanstack/react-db import { createRxDatabase, addRxPlugin } from 'rxdb/plugins/core' /** - * Here we use the localstorage based storage for RxDB. - * RxDB has a wide range of storages based on Dexie.js, IndexedDB, SQLite and more. + * Here we use the localStorage based storage for RxDB. + * RxDB has a wide range of storages based on Dexie.js, IndexedDB, SQLite, and more. */ import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage' @@ -93,7 +93,7 @@ import { rxdbCollectionOptions } from '@tanstack/rxdb-db-collection' const todosCollection = createCollection( rxdbCollectionOptions({ - rxCollection: myDatabase.todos, + rxCollection: db.todos, startSync: true, // start ingesting RxDB data immediately }) ) @@ -118,7 +118,7 @@ The `rxdbCollectionOptions` function accepts the following options: ### Optional - `id`: Unique identifier for the collection -- `schema`: Schema for validating items. RxDB already has schema validation but having additional validation on the TanStack DB side can help to unify error handling between different tanstack collections. +- `schema`: Schema for validating items. RxDB already has schema validation but having additional validation on the TanStack DB side can help to unify error handling between different TanStack collections. - `startSync`: Whether to start syncing immediately (default: true) - `onInsert, onUpdate, onDelete`: Override default persistence handlers. By default, TanStack DB writes are persisted to RxDB using bulkUpsert, patch, and bulkRemove. - `syncBatchSize`: The maximum number of documents fetched per batch during the initial sync from RxDB into TanStack DB (default: 1000). Larger values reduce round trips but use more memory; smaller values are lighter but may increase query calls. Note that this only affects the initial sync. Ongoing live updates are streamed one by one via RxDB's change feed. @@ -138,7 +138,7 @@ This separation of concerns means you configure replication entirely in RxDB, an ### Do I still need RxDB schema indexes if I only query TanStack DB? -Usually not for TanStack DB queries themselves. TanStack DB queries run entirely in memory, so RxDB schema indexes do not affect the performance of TanStack DB's live queries. However, RxDB indexes may still be important if: +Usually not, at least for TanStack DB queries themselves. TanStack DB queries run entirely in memory, so RxDB schema indexes do not affect the performance of TanStack DB's live queries. However, RxDB indexes may still be important if: - You run queries directly against RxDB (e.g. `rxCollection.find(...)`). - Your replication setup uses filtered queries or selectors. - You rely on RxDB to selectively load subsets of data instead of hydrating everything into memory. From 44e711db3473506171218a5caab516376a5f08ad Mon Sep 17 00:00:00 2001 From: pubkey <8926560+pubkey@users.noreply.github.com> Date: Fri, 23 Jan 2026 12:10:37 +0100 Subject: [PATCH 3/5] ADD docs generation --- scripts/generate-docs.ts | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index e9a6da6c5..846be229e 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -51,6 +51,21 @@ await generateReferenceDocs({ ), exclude: [`packages/db/**/*`], }, + { + name: `rxdb-db-collection`, + entryPoints: [ + resolve(__dirname, `../packages/rxdb-db-collection/src/index.ts`), + ], + tsconfig: resolve( + __dirname, + `../packages/rxdb-db-collection/tsconfig.docs.json`, + ), + outputDir: resolve( + __dirname, + `../docs/reference/rxdb-db-collection`, + ), + exclude: [`packages/db/**/*`], + }, { name: `react-db`, entryPoints: [resolve(__dirname, `../packages/react-db/src/index.ts`)], From f705ced012dbcae70cc84753cb9d8085ef0dde9c Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 11:11:26 +0000 Subject: [PATCH 4/5] ci: apply automated fixes --- scripts/generate-docs.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index 846be229e..cbedd2a3c 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -60,10 +60,7 @@ await generateReferenceDocs({ __dirname, `../packages/rxdb-db-collection/tsconfig.docs.json`, ), - outputDir: resolve( - __dirname, - `../docs/reference/rxdb-db-collection`, - ), + outputDir: resolve(__dirname, `../docs/reference/rxdb-db-collection`), exclude: [`packages/db/**/*`], }, { From 1cc733b6562d086cbeee7d300fba6728f353d1bc Mon Sep 17 00:00:00 2001 From: pubkey <8926560+pubkey@users.noreply.github.com> Date: Fri, 23 Jan 2026 14:22:56 +0100 Subject: [PATCH 5/5] ADD missing RxDB generated docs --- .../functions/rxdbCollectionOptions.md | 66 ++++++++++++++++++ .../functions/stripRxdbFields.md | 28 ++++++++ docs/reference/rxdb-db-collection/index.md | 19 ++++++ .../type-aliases/RxDBCollectionConfig.md | 68 +++++++++++++++++++ .../variables/OPEN_RXDB_SUBSCRIPTIONS.md | 14 ++++ 5 files changed, 195 insertions(+) create mode 100644 docs/reference/rxdb-db-collection/functions/rxdbCollectionOptions.md create mode 100644 docs/reference/rxdb-db-collection/functions/stripRxdbFields.md create mode 100644 docs/reference/rxdb-db-collection/index.md create mode 100644 docs/reference/rxdb-db-collection/type-aliases/RxDBCollectionConfig.md create mode 100644 docs/reference/rxdb-db-collection/variables/OPEN_RXDB_SUBSCRIPTIONS.md diff --git a/docs/reference/rxdb-db-collection/functions/rxdbCollectionOptions.md b/docs/reference/rxdb-db-collection/functions/rxdbCollectionOptions.md new file mode 100644 index 000000000..aa721dd51 --- /dev/null +++ b/docs/reference/rxdb-db-collection/functions/rxdbCollectionOptions.md @@ -0,0 +1,66 @@ +--- +id: rxdbCollectionOptions +title: rxdbCollectionOptions +--- + +# Function: rxdbCollectionOptions() + +## Call Signature + +```ts +function rxdbCollectionOptions(config): CollectionConfig, string, T, UtilsRecord> & object; +``` + +Defined in: [rxdb.ts:89](https://github.com/pubkey/tanstack-db-rxdb/blob/main/packages/rxdb-db-collection/src/rxdb.ts#L89) + +Creates RxDB collection options for use with a standard Collection + +### Type Parameters + +#### T + +`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\> + +### Parameters + +#### config + +[`RxDBCollectionConfig`](../type-aliases/RxDBCollectionConfig.md)\<`InferSchemaOutput`\<`T`\>, `T`\> + +Configuration options for the RxDB collection + +### Returns + +`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `string`, `T`, `UtilsRecord`\> & `object` + +Collection options with utilities + +## Call Signature + +```ts +function rxdbCollectionOptions(config): CollectionConfig & object; +``` + +Defined in: [rxdb.ts:96](https://github.com/pubkey/tanstack-db-rxdb/blob/main/packages/rxdb-db-collection/src/rxdb.ts#L96) + +Creates RxDB collection options for use with a standard Collection + +### Type Parameters + +#### T + +`T` *extends* `object` + +### Parameters + +#### config + +`Omit`\<`BaseCollectionConfig`\<`T`, `string`, `never`, `UtilsRecord`, `any`\>, `"onInsert"` \| `"onUpdate"` \| `"onDelete"` \| `"getKey"`\> & `object` & `object` + +Configuration options for the RxDB collection + +### Returns + +`CollectionConfig`\<`T`, `string`, `never`, `UtilsRecord`\> & `object` + +Collection options with utilities diff --git a/docs/reference/rxdb-db-collection/functions/stripRxdbFields.md b/docs/reference/rxdb-db-collection/functions/stripRxdbFields.md new file mode 100644 index 000000000..97af6ee07 --- /dev/null +++ b/docs/reference/rxdb-db-collection/functions/stripRxdbFields.md @@ -0,0 +1,28 @@ +--- +id: stripRxdbFields +title: stripRxdbFields +--- + +# Function: stripRxdbFields() + +```ts +function stripRxdbFields(obj): T; +``` + +Defined in: [helper.ts:8](https://github.com/pubkey/tanstack-db-rxdb/blob/main/packages/rxdb-db-collection/src/helper.ts#L8) + +## Type Parameters + +### T + +`T` *extends* `Record`\<`string`, `unknown`\> + +## Parameters + +### obj + +`T` + +## Returns + +`T` diff --git a/docs/reference/rxdb-db-collection/index.md b/docs/reference/rxdb-db-collection/index.md new file mode 100644 index 000000000..4ab546bdc --- /dev/null +++ b/docs/reference/rxdb-db-collection/index.md @@ -0,0 +1,19 @@ +--- +id: "@tanstack/rxdb-db-collection" +title: "@tanstack/rxdb-db-collection" +--- + +# @tanstack/rxdb-db-collection + +## Type Aliases + +- [RxDBCollectionConfig](type-aliases/RxDBCollectionConfig.md) + +## Variables + +- [OPEN\_RXDB\_SUBSCRIPTIONS](variables/OPEN_RXDB_SUBSCRIPTIONS.md) + +## Functions + +- [rxdbCollectionOptions](functions/rxdbCollectionOptions.md) +- [stripRxdbFields](functions/stripRxdbFields.md) diff --git a/docs/reference/rxdb-db-collection/type-aliases/RxDBCollectionConfig.md b/docs/reference/rxdb-db-collection/type-aliases/RxDBCollectionConfig.md new file mode 100644 index 000000000..8a0a7dc7e --- /dev/null +++ b/docs/reference/rxdb-db-collection/type-aliases/RxDBCollectionConfig.md @@ -0,0 +1,68 @@ +--- +id: RxDBCollectionConfig +title: RxDBCollectionConfig +--- + +# Type Alias: RxDBCollectionConfig\ + +```ts +type RxDBCollectionConfig = Omit, "onInsert" | "onUpdate" | "onDelete" | "getKey"> & object; +``` + +Defined in: [rxdb.ts:49](https://github.com/pubkey/tanstack-db-rxdb/blob/main/packages/rxdb-db-collection/src/rxdb.ts#L49) + +Configuration interface for RxDB collection options + +## Type Declaration + +### rxCollection + +```ts +rxCollection: RxCollection; +``` + +The RxCollection from a RxDB Database instance. + +### syncBatchSize? + +```ts +optional syncBatchSize: number; +``` + +The maximum number of documents to read from the RxDB collection +in a single batch during the initial sync between RxDB and the +in-memory TanStack DB collection. + +#### Remarks + +- Defaults to `1000` if not specified. +- Larger values reduce the number of round trips to the storage + engine but increase memory usage per batch. +- Smaller values may lower memory usage and allow earlier + streaming of initial results, at the cost of more query calls. + +Adjust this depending on your expected collection size and +performance characteristics of the chosen RxDB storage adapter. + +## Type Parameters + +### T + +`T` *extends* `object` = `Record`\<`string`, `unknown`\> + +The explicit type of items in the collection (highest priority). Use the document type of your RxCollection here. + +### TSchema + +`TSchema` *extends* `StandardSchemaV1` = `never` + +The schema type for validation and type inference (second priority) + +## Remarks + +Type resolution follows a priority order: +1. If you provide an explicit type via generic parameter, it will be used +2. If no explicit type is provided but a schema is, the schema's output type will be inferred + +You should provide EITHER an explicit type OR a schema, but not both, as they would conflict. +Notice that primary keys in RxDB must always be a string. diff --git a/docs/reference/rxdb-db-collection/variables/OPEN_RXDB_SUBSCRIPTIONS.md b/docs/reference/rxdb-db-collection/variables/OPEN_RXDB_SUBSCRIPTIONS.md new file mode 100644 index 000000000..76dab1c29 --- /dev/null +++ b/docs/reference/rxdb-db-collection/variables/OPEN_RXDB_SUBSCRIPTIONS.md @@ -0,0 +1,14 @@ +--- +id: OPEN_RXDB_SUBSCRIPTIONS +title: OPEN_RXDB_SUBSCRIPTIONS +--- + +# Variable: OPEN\_RXDB\_SUBSCRIPTIONS + +```ts +const OPEN_RXDB_SUBSCRIPTIONS: WeakMap>; +``` + +Defined in: [rxdb.ts:31](https://github.com/pubkey/tanstack-db-rxdb/blob/main/packages/rxdb-db-collection/src/rxdb.ts#L31) + +Used in tests to ensure proper cleanup