Move collections to own packages (#252)

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

.changeset/chubby-turkeys-sell.md

@@ -0,0 +1,21 @@
+---
+"@tanstack/db-electric-collection": patch
+"@tanstack/db-query-collection": patch
+"@tanstack/db-example-react-todo": patch
+"@tanstack/db": patch
+---
+
+Move Collections to their own packages
+
+- Move local-only and local-storage collections to main `@tanstack/db` package
+- Create new `@tanstack/electric-db-collection` package for Electric SQL integration
+- Create new `@tanstack/query-db-collection` package for TanStack Query integration
+- Delete `@tanstack/db-collections` package (removed from repo)
+- Update example app and documentation to use new package structure
+
+Why?
+
+- Better separation of concerns
+- Independent versioning for each collection type
+- Cleaner dependencies (electric collections don't need query deps, etc.)
+- Easier to add more collection types moving forward

README.md

@@ -48,14 +48,18 @@ TanStack DB is **backend agnostic** and **incrementally adoptable**:
 Sync data into collections:
 
 ```ts
-import { createQueryCollection } from "@tanstack/db-collections"
-
-const todoCollection = createQueryCollection({
-  queryKey: ["todos"],
-  queryFn: async () => fetch("/api/todos"),
-  getKey: (item) => item.id,
-  schema: todoSchema, // any standard schema
-})
+import { createCollection, QueryClient } from "@tanstack/react-db"
+import { queryCollectionOptions } from "@tanstack/query-db-collection"
+
+const todoCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["todos"],
+    queryFn: async () => fetch("/api/todos"),
+    queryClient: new QueryClient(),
+    getKey: (item) => item.id,
+    schema: todoSchema, // any standard schema
+  })
+)
 ```
 
 Use live queries in your components:
@@ -135,7 +139,9 @@ There's also an example [React todo app](./examples/react/todo) and usage exampl
 ## 🔧 Install
 
 ```bash
-npm install @tanstack/react-db @tanstack/db-collections
+npm install @tanstack/react-db
+# Optional: for specific collection types
+npm install @tanstack/electric-db-collection @tanstack/query-db-collection
 ```
 
 Other framework integrations are in progress.

examples/react/todo/package.json

@@ -3,8 +3,9 @@
   "private": true,
   "version": "0.0.26",
   "dependencies": {
-    "@tanstack/db-collections": "^0.0.24",
-    "@tanstack/query-core": "^5.81.5",
+    "@tanstack/electric-db-collection": "^0.0.2",
+    "@tanstack/query-core": "^5.75.7",
+    "@tanstack/query-db-collection": "^0.0.2",
     "@tanstack/react-db": "^0.0.19",
     "@tanstack/react-router": "^1.125.6",
     "@tanstack/react-start": "^1.126.1",

examples/react/todo/src/api/server.ts

@@ -8,7 +8,7 @@ import {
   validateUpdateTodo,
 } from "../db/validation"
 import type { Express } from "express"
-import type { Txid } from "@tanstack/db-collections"
+import type { Txid } from "@tanstack/electric-db-collection"
 
 // Create Express app
 const app: Express = express()

examples/react/todo/src/lib/collections.ts

@@ -1,8 +1,6 @@
 import { createCollection } from "@tanstack/react-db"
-import {
-  electricCollectionOptions,
-  queryCollectionOptions,
-} from "@tanstack/db-collections"
+import { electricCollectionOptions } from "@tanstack/electric-db-collection"
+import { queryCollectionOptions } from "@tanstack/query-db-collection"
 import { QueryClient } from "@tanstack/query-core"
 import { selectConfigSchema, selectTodoSchema } from "../db/validation"
 import { api } from "./api"

examples/react/todo/src/routes/api/config.$id.ts

@@ -2,7 +2,7 @@ import { createServerFileRoute } from "@tanstack/react-start/server"
 import { json } from "@tanstack/react-start"
 import { sql } from "../../db/postgres"
 import { validateUpdateConfig } from "../../db/validation"
-import type { Txid } from "@tanstack/db-collections"
+import type { Txid } from "@tanstack/electric-db-collection"
 
 // Generate a transaction ID
 async function generateTxId(tx: any): Promise<Txid> {

examples/react/todo/src/routes/api/config.ts

@@ -2,7 +2,7 @@ import { createServerFileRoute } from "@tanstack/react-start/server"
 import { json } from "@tanstack/react-start"
 import { sql } from "../../db/postgres"
 import { validateInsertConfig } from "../../db/validation"
-import type { Txid } from "@tanstack/db-collections"
+import type { Txid } from "@tanstack/electric-db-collection"
 
 // Generate a transaction ID
 async function generateTxId(tx: any): Promise<Txid> {

examples/react/todo/src/routes/api/todos.$id.ts

@@ -2,7 +2,7 @@ import { createServerFileRoute } from "@tanstack/react-start/server"
 import { json } from "@tanstack/react-start"
 import { sql } from "../../db/postgres"
 import { validateUpdateTodo } from "../../db/validation"
-import type { Txid } from "@tanstack/db-collections"
+import type { Txid } from "@tanstack/electric-db-collection"
 
 // Generate a transaction ID
 async function generateTxId(tx: any): Promise<Txid> {

examples/react/todo/src/routes/api/todos.ts

@@ -2,7 +2,7 @@ import { createServerFileRoute } from "@tanstack/react-start/server"
 import { json } from "@tanstack/react-start"
 import { sql } from "../../db/postgres"
 import { validateInsertTodo } from "../../db/validation"
-import type { Txid } from "@tanstack/db-collections"
+import type { Txid } from "@tanstack/electric-db-collection"
 
 // Generate a transaction ID
 async function generateTxId(tx: any): Promise<Txid> {

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db-monorepo",
   "private": true,
-  "description": "Optimistic UI library for sync engines",
+  "description": "Reactive client queryable store for sync-first applications",
   "version": "0.0.0",
   "repository": {
     "type": "git",