Add warning for preload on on-demand collections (#871)

KyleAMathews · claude · web-flow · commit 15c772f5e42e · 2025-11-21T07:40:38.000-07:00
* feat: warn when calling preload() on on-demand collections

Calling .preload() on a collection with syncMode "on-demand" is a no-op
since data is only loaded when queries request it. This change adds a
warning to help users understand this behavior and suggests creating a
live query instead.

The warning includes a link to the Query-Driven Sync blog post for
additional context and guidance.

* chore: add changeset for preload on-demand warning

---------

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/warm-preload-on-demand.md b/.changeset/warm-preload-on-demand.md
@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add warning when calling `.preload()` on collections with `on-demand` syncMode. In on-demand mode, data is only loaded when queries request it, so calling `.preload()` on the collection itself is a no-op. Users should create a live query and call `.preload()` on that instead.
diff --git a/packages/db/src/collection/sync.ts b/packages/db/src/collection/sync.ts
@@ -231,6 +231,16 @@ export class CollectionSyncManager<
       return this.preloadPromise
     }
 
+    // Warn when calling preload on an on-demand collection
+    if (this.syncMode === `on-demand`) {
+      console.warn(
+        `${this.id ? `[${this.id}] ` : ``}Calling .preload() on a collection with syncMode "on-demand" is a no-op. ` +
+          `In on-demand mode, data is only loaded when queries request it. ` +
+          `Instead, create a live query and call .preload() on that to load the specific data you need. ` +
+          `See https://tanstack.com/blog/tanstack-db-0.5-query-driven-sync for more details.`
+      )
+    }
+
     this.preloadPromise = new Promise<void>((resolve, reject) => {
       if (this.lifecycle.status === `ready`) {
         resolve()

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@tanstack/db": patch
 +---
++
 +Add warning when calling `.preload()` on collections with `on-demand` syncMode. In on-demand mode, data is only loaded when queries request it, so calling `.preload()` on the collection itself is a no-op. Users should create a live query and call `.preload()` on that instead.