diff --git a/.changeset/warm-preload-on-demand.md b/.changeset/warm-preload-on-demand.md new file mode 100644 index 000000000..a8093e44b --- /dev/null +++ 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 index e0f06d572..0485558a8 100644 --- 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((resolve, reject) => { if (this.lifecycle.status === `ready`) { resolve()