Skip to content

Commit fbed513

Browse files
LadyBluenotesKyleAMathews
LadyBluenotes
and
KyleAMathews
authored
Update README (#561)
Co-authored-by: Kyle Mathews <[email protected]>
1 parent 72fc263 commit fbed513

File tree

3 files changed

+138
-183
lines changed

3 files changed

+138
-183
lines changed

‎README.md‎

Lines changed: 112 additions & 183 deletions
Original file line numberDiff line numberDiff line change
@@ -1,198 +1,127 @@
1-
# TanStack DB
2-
3-
<!-- ![TanStack DB Header](https://github.com/tanstack/db/raw/main/media/repo-header.png) -->
4-
5-
**A reactive client store for building super fast apps on sync**
6-
7-
TanStack DB extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
8-
9-
<p>
10-
<a href="https://x.com/intent/post?text=TanStack%20DB&url=https://tanstack.com/db">
11-
<img alt="#TanStack" src="https://img.shields.io/twitter/url?color=%2308a0e9&label=%23TanStack&style=social&url=https%3A%2F%2Ftwitter.com%2Fintent%2Ftweet%3Fbutton_hashtag%3DTanStack" /></a>
12-
<a href="#status">
13-
<img src="https://img.shields.io/badge/status-beta-yellow" alt="Status - BETA"></a>
14-
<a href="https://npmjs.com/package/@tanstack/db">
15-
<img alt="" src="https://img.shields.io/npm/dm/@tanstack/db.svg" /></a>
16-
<a href="https://discord.gg/yjUNbvbraC">
17-
<img alt="" src="https://img.shields.io/badge/Discord-TanStack-%235865F2" /></a>
18-
<a href="https://github.com/tanstack/db/discussions">
19-
<img alt="Join the discussion on Github" src="https://img.shields.io/badge/Discussions-Chat%20now!-green" /></a>
20-
<a href="https://x.com/tan_stack">
21-
<img alt="" src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social&label=Follow @TanStack" /></a>
22-
</p>
23-
24-
Enjoy this library? Try the entire [TanStack](https://tanstack.com), including [TanStack Query](https://tanstack.com/query), [TanStack Store](https://tanstack.com/store), etc.
25-
26-
## 🚀 Why TanStack DB?
27-
28-
TanStack DB gives you robust support for real-time sync, live queries and local writes. With no stale data, super fast re-rendering and sub-millisecond cross-collection queries — even for large complex apps.
29-
30-
Built on a TypeScript implementation of differential dataflow ([#](https://github.com/electric-sql/d2ts)), TanStack DB gives you:
31-
32-
- 🔥 **a blazing fast query engine**<br />
33-
for sub-millisecond live queries &mdash; even for complex queries with joins and aggregates
34-
- 🎯 **fine-grained reactivity**<br />
35-
to minimize component re-rendering
36-
- 💪 **robust transaction primitives**<br />
37-
for easy optimistic mutations with sync and lifecycle support
38-
- 🌟 **normalized data**<br />
39-
to keep your backend simple
40-
41-
TanStack DB is **backend agnostic** and **incrementally adoptable**:
42-
43-
- plug in any backend: sync engines, REST APIs, GraphQL, polling, custom sources
44-
- builds on [TanStack Store](https://tanstack.com/store), works with and alongside [TanStack Query](https://tanstack.com/query)
45-
46-
## 💥 Usage example
47-
48-
Sync data into collections:
49-
50-
```ts
51-
import { createCollection, QueryClient } from "@tanstack/react-db"
52-
import { queryCollectionOptions } from "@tanstack/query-db-collection"
53-
54-
const todoCollection = createCollection(
55-
queryCollectionOptions({
56-
queryKey: ["todos"],
57-
queryFn: async () => fetch("/api/todos"),
58-
queryClient: new QueryClient(),
59-
getKey: (item) => item.id,
60-
schema: todoSchema, // any standard schema
61-
})
62-
)
63-
```
64-
65-
Use live queries in your components:
66-
67-
```tsx
68-
import { useLiveQuery } from "@tanstack/react-db"
69-
import { eq } from "@tanstack/db"
70-
71-
const Todos = () => {
72-
const { data: todos } = useLiveQuery((query) =>
73-
query
74-
.from({ todos: todoCollection })
75-
.where(({ todos }) => eq(todos.completed, false))
76-
)
77-
78-
return <List items={todos} />
79-
}
80-
```
81-
82-
Apply mutations with local optimistic state:
83-
84-
```tsx
85-
// Define collection with persistence handlers
86-
const todoCollection = createCollection({
87-
id: "todos",
88-
// ... other config
89-
onInsert: async ({ transaction }) => {
90-
const modified = transaction.mutations[0].modified
91-
await api.todos.create(modified)
92-
},
93-
})
94-
95-
// Then use collection operators in your components
96-
const AddTodo = () => {
97-
return (
98-
<Button
99-
onClick={() =>
100-
todoCollection.insert({
101-
id: uuid(),
102-
text: "🔥 Make app faster",
103-
completed: false,
104-
})
105-
}
106-
/>
107-
)
108-
}
109-
```
110-
111-
## 📚 Docs
112-
113-
See the [Usage guide](./docs/overview.md) for more details, including how to do:
1+
<div align="center">
2+
<img src="./media/header_db.png" >
3+
</div>
4+
5+
<br />
6+
7+
<div align="center">
8+
<a href="https://npmjs.com/package/@tanstack/db" target="\_parent">
9+
<img alt="" src="https://img.shields.io/npm/dm/@tanstack/db.svg" alt="npm downloads" />
10+
</a>
11+
<a href="https://github.com/TanStack/db" target="\_parent">
12+
<img alt="" src="https://img.shields.io/github/stars/TanStack/db.svg?style=social&label=Star" alt="GitHub stars" />
13+
</a>
14+
<a href="https://bundlejs.com/?q=%40tanstack%2Fdb&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22react-dom%22%5D%7D%7D&badge=" target="\_parent">
15+
<img alt="" src="https://deno.bundlejs.com/?q=@tanstack/db&config={%22esbuild%22:{%22external%22:[%22react%22,%22react-dom%22]}}&badge=detailed" alt="Bundle size" />
16+
</a>
17+
</div>
18+
19+
<div align="center">
20+
<a href="#status">
21+
<img src="https://img.shields.io/badge/status-beta-yellow" alt="Status - BETA">
22+
</a>
23+
<a href="https://bestofjs.org/projects/tanstack-db">
24+
<img alt="Best of JS" src="https://img.shields.io/endpoint?url=https://bestofjs-serverless.now.sh/api/project-badge?fullName=TanStack%2Fdb%26since=daily" alt="Best of JS"/>
25+
</a>
26+
<a href="https://twitter.com/tan_stack">
27+
<img src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social" alt="Follow @TanStack"/>
28+
</a>
29+
</div>
30+
31+
<div align="center">
32+
33+
### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
34+
</div>
11435

115-
- real-time sync
116-
- cross-collection queries
117-
- fine-grained reactivity
118-
- different strategies for data loading and handling mutations
119-
120-
There's also an example [React todo app](./examples/react/todo) and usage examples in the [package tests](./packages/db/tests).
121-
122-
## 🧱 Core concepts
123-
124-
### Collections
125-
126-
- typed sets of objects that can mirror a backend table or be populated with a filtered view or result set, such as `pendingTodos` or `decemberNewTodos`
127-
- collections are just JavaScript data &mdash; load them on demand and define as many as you need
128-
129-
### Live queries
130-
131-
- run reactively against and across collections with support for joins, filters and aggregates
132-
- powered by differential dataflow: query results update incrementally, not by re-running the whole query
133-
134-
### Transactional mutators
135-
136-
- batch and stage local changes across collections with immediate application of local optimistic updates
137-
- sync transactions to the backend with automatic rollbacks and management of optimistic state
138-
139-
## 📦 Collection Types
140-
141-
TanStack DB provides several collection types to support different backend integrations:
142-
143-
- **`@tanstack/db`** - Core collection functionality with local-only and local-storage collections for offline-first applications
144-
- **`@tanstack/query-db-collection`** - Collections backed by [TanStack Query](https://tanstack.com/query) for REST APIs and GraphQL endpoints
145-
- **`@tanstack/electric-db-collection`** - Real-time sync collections powered by [ElectricSQL](https://electric-sql.com) for live database synchronization
146-
- **`@tanstack/trailbase-db-collection`** - Collections for [TrailBase](https://trailbase.io) backend integration
147-
- **`@tanstack/rxdb-db-collection`** - Collections backed by [RxDB](https://rxdb.info), a client-side database with replication support and local persistence made for local-first apps.
148-
149-
## Framework integrations
150-
151-
TanStack DB integrates with React & Vue with more on the way!
152-
153-
- **`@tanstack/react-db`** - React hooks and components for using TanStack DB collections in React applications
154-
- **`@tanstack/vue-db`** - Vue composables for using TanStack DB collections in Vue applications
155-
156-
## 🔧 Install
157-
158-
```bash
159-
npm install @tanstack/react-db
160-
# Optional: for specific collection types
161-
npm install @tanstack/electric-db-collection @tanstack/query-db-collection @tanstack/trailbase-db-collection @tanstack/rxdb-db-collection
162-
```
36+
# TanStack DB
16337

164-
Other framework integrations are in progress.
38+
> Tanstack DB is currently in BETA. See [the release post](https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query) for more details.
16539
166-
## ❓ FAQ
40+
A reactive client store that lets you build fast, sync‑driven apps with a backend‑agnostic real‑time data layer:
16741

168-
**How is this different from TanStack Query?**<br />
169-
TanStack DB builds _on top of_ TanStack Query. Use Query to fetch data; use DB to manage reactive local collections and mutations. They complement each other.
42+
- Blazing‑fast query engine for sub‑millisecond live queries, joins & aggregates
43+
- Fine‑grained reactivity to minimize component re‑rendering
44+
- Robust transaction primitives for optimistic mutations with sync & lifecycle support
45+
- Normalized data model that keeps backends simple and consistent
17046

171-
**Do I need a sync engine like ElectricSQL?**<br />
172-
No. TanStack DB _is_ designed to work with sync engines like [Electric](https://electric-sql.com) but _also_ works with any backend: polling APIs, GraphQL, REST, or custom sync logic.
47+
<a href="https://tanstack.com/db" style="font-weight:bold" >Read the docs →</a>
48+
<br />
17349

174-
**What is a Collection? Is it like a DB table?**<br />
175-
Kind of. Collections are typed sets of objects, but they can also be filtered views or custom groupings. They're just JavaScript structures that you define and manage.
50+
## Get Involved
17651

177-
**Is this an ORM? Do queries hit my backend?**<br />
178-
No. TanStack DB is not an ORM. Queries run entirely in the client against local collections. The framework provides strong primitives to manage how data is loaded and synced.
52+
- We welcome issues and pull requests!
53+
- Participate in [GitHub discussions](https://github.com/TanStack/db/discussions)
54+
- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ)
55+
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions
17956

18057
## Partners
18158

59+
<table align="center">
60+
<tr>
61+
<td>
62+
<a href="https://www.coderabbit.ai/?via=tanstack&dub_id=aCcEEdAOqqutX6OS" >
63+
<picture>
64+
<source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-CMcuvjEy.svg" height="40" />
65+
<source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" />
66+
<img src="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" alt="CodeRabbit" />
67+
</picture>
68+
</a>
69+
</td>
70+
<td>
71+
<a href="https://www.cloudflare.com?utm_source=tanstack">
72+
<picture>
73+
<source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-DQDB7UaL.svg" height="60" />
74+
<source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" />
75+
<img src="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" alt="Cloudflare" />
76+
</picture>
77+
</a>
78+
</td>
79+
</tr>
80+
<tr>
81+
<td>
18282
<a href="https://electric-sql.com">
183-
<img alt="ElectricSQL logo"
184-
src="https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo.with-background.sm.png"
185-
/>
83+
<picture>
84+
<source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/electric-dark-Bfu2Vl2j.svg" height="60">
85+
<source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/electric-light-C-5MDda4.svg" height="60">
86+
<img src="https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo.with-background.sm.png" height="60" alt="ElectricSQL logo"/>
87+
</picture>
18688
</a>
89+
</td>
90+
<td>
91+
<a href="https://www.prisma.io?utm_source=tanstack&via=tanstack">
92+
<picture>
93+
<source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/prisma-dark-DwgDxLwn.svg" height="60">
94+
<source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/prisma-light-Cloa3Onm.svg" height="60">
95+
<img src="https://tanstack.com/assets/prisma-dark-DwgDxLwn.svg" height="60" alt="Prisma"/>
96+
</picture>
97+
</a>
98+
</td>
99+
</tr>
100+
</table>
187101

188-
## Status
189-
190-
Tanstack DB is currently in BETA. See [the release post](https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query) for more details.
191-
192-
## Contributing
193-
194-
View the contributing guidelines [here](https://github.com/TanStack/query/blob/main/CONTRIBUTING.md).
195-
196-
### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
102+
<div align="center">
103+
<img src="./media/partner_logo.svg" alt="DB & you?" height="65">
104+
<p>
105+
We're looking for TanStack DB Partners to join our mission! Partner with us to push the boundaries of TanStack DB and build amazing things together.
106+
</p>
107+
<a href="mailto:[email protected]?subject=TanStack DB Partnership"><b>LET'S CHAT</b></a>
108+
</div>
109+
110+
## Explore the TanStack Ecosystem
111+
112+
- <a href="https://github.com/tanstack/config"><b>TanStack Config</b></a> – Tooling for JS/TS packages
113+
- <a href="https://github.com/tanstack/devtools"><b>TanStack DevTools</b></a> – Unified devtools panel
114+
- <a href="https://github.com/tanstack/form"><b>TanStack Form</b></a> – Type‑safe form state
115+
- <a href="https://github.com/tanstack/pacer"><b>TanStack Pacer</b></a> – Debouncing, throttling, batching <br/>
116+
- <a href="https://github.com/tanstack/query"><b>TanStack Query</b></a> – Async state & caching
117+
- <a href="https://github.com/tanstack/ranger"><b>TanStack Ranger</b></a> – Range & slider primitives
118+
- <a href="https://github.com/tanstack/router"><b>TanStack Router</b></a> – Type‑safe routing, caching & URL state
119+
- <a href="https://github.com/tanstack/router"><b>TanStack Start</b></a> – Full‑stack SSR & streaming
120+
- <a href="https://github.com/tanstack/store"><b>TanStack Store</b></a> – Reactive data store
121+
- <a href="https://github.com/tanstack/table"><b>TanStack Table</b></a> – Headless datagrids
122+
- <a href="https://github.com/tanstack/virtual"><b>TanStack Virtual</b></a> – Virtualized rendering
123+
124+
… and more at <a href="https://tanstack.com"><b>TanStack.com »</b></a>
125+
v>
197126

198127
<!-- Use the force, Luke -->

‎media/header_db.png‎

127 KB
Loading

‎media/partner_logo.svg‎

Lines changed: 26 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)