Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

README.md

275 lines8.4 KB

1This is a TanStack Start project with tRPC API running on Start's server functions so it's easily deployable to many hosting platforms.
2​
3All reads from the Postgres database are done via tRPC queries which populate TanStack DB query collections.
4​
5We sync normalized data from tables into TanStack DB collections in the client & then write client-side queries for displaying data in components.
6​
7# Getting Started
8​
9## Create a new project
10​
11To create a new project based on this starter, run the following commands:
12​
13```
14npx gitpick tanstack/db/tree/main/examples/react/projects my-tanstack-db-project
15cd my-tanstack-db-project
16```
17​
18Copy the .env.example file to .env and fill in the values.
19​
20_The database url will be set by default to development postgres docker container, and during development the better-auth secret is not required._
21​
22```
23cp .env.example .env
24```
25​
26## Running the Application
27​
28**Note: Docker is required to run this starter**
29​
30To run this application:
31​
32```bash
33npm install
34npm run dev
35​
36# From a separate terminal
37npm run migrate
38```
39​
40# Building For Production
41​
42To build this application for production:
43​
44```bash
45npm run build
46```
47​
48## Testing
49​
50This project uses [Vitest](https://vitest.dev/) for testing. You can run the tests with:
51​
52```bash
53npm run test
54```
55​
56## AI
57​
58The starter includes an `AGENT.md`. Depending on which AI coding tool you use, you may need to copy/move it to the right file name e.g. `.cursor/rules`.
59​
60## Styling
61​
62This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
63​
64## Routing
65​
66This project uses [TanStack Router](https://tanstack.com/router). The initial setup is a file based router. Which means that the routes are managed as files in `src/routes`.
67​
68### Adding A Route
69​
70To add a new route to your application just add another a new file in the `./src/routes` directory.
71​
72TanStack will automatically generate the content of the route file for you.
73​
74Now that you have two routes you can use a `Link` component to navigate between them.
75​
76### Adding Links
77​
78To use SPA (Single Page Application) navigation you will need to import the `Link` component from `@tanstack/react-router`.
79​
80```tsx
81import { Link } from '@tanstack/react-router'
82```
83​
84Then anywhere in your JSX you can use it like so:
85​
86```tsx
87<Link to="/about">About</Link>
88```
89​
90This will create a link that will navigate to the `/about` route.
91​
92More information on the `Link` component can be found in the [Link documentation](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
93​
94### Using A Layout
95​
96In the File Based Routing setup the layout is located in `src/routes/__root.tsx`. Anything you add to the root route will appear in all the routes. The route content will appear in the JSX where you use the `<Outlet />` component.
97​
98Here is an example layout that includes a header:
99​
100```tsx
101import { Outlet, createRootRoute } from '@tanstack/react-router'
102import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
103​
104import { Link } from '@tanstack/react-router'
105​
106export const Route = createRootRoute({
107 component: () => (
108 <>
109 <header>
110 <nav>
111 <Link to="/">Home</Link>
112 <Link to="/about">About</Link>
113 </nav>
114 </header>
115 <Outlet />
116 <TanStackRouterDevtools />
117 </>
118 ),
119})
120```
121​
122The `<TanStackRouterDevtools />` component is not required so you can remove it if you don't want it in your layout.
123​
124More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
125​
126## Data Fetching
127​
128There are multiple ways to fetch data in your application. You can use TanStack DB to fetch data from a server. But you can also use the `loader` functionality built into TanStack Router to load the data for a route before it's rendered.
129​
130For example:
131​
132```tsx
133const peopleRoute = createRoute({
134 getParentRoute: () => rootRoute,
135 path: '/people',
136 loader: async () => {
137 const response = await fetch('https://swapi.dev/api/people')
138 return response.json() as Promise<{
139 results: {
140 name: string
141 }[]
142 }>
143 },
144 component: () => {
145 const data = peopleRoute.useLoaderData()
146 return (
147 <ul>
148 {data.results.map((person) => (
149 <li key={person.name}>{person.name}</li>
150 ))}
151 </ul>
152 )
153 },
154})
155```
156​
157Loaders simplify your data fetching logic dramatically. Check out more information in the [Loader documentation](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#loader-parameters).
158​
159### TanStack DB with Query Collections
160​
161TanStack DB gives you robust support for live queries and optimistic mutations. With no stale data, super fast re-rendering and sub-millisecond cross-collection queries — even for large complex apps.
162​
163Built on a TypeScript implementation of differential dataflow, TanStack DB provides:
164​
165- 🔥 **Blazing fast query engine** - sub-millisecond live queries, even for complex queries with joins and aggregates
166- 🎯 **Fine-grained reactivity** - minimize component re-rendering
167- 💪 **Robust transaction primitives** - easy optimistic mutations with sync and lifecycle support
168- 🌟 **Normalized data** - keep your backend simple
169​
170#### Core Concepts
171​
172**Collections** - Typed sets of objects that can mirror a backend table or be populated with filtered views like `pendingTodos` or `decemberNewTodos`. Collections are just JavaScript data that you can load on demand.
173​
174**Live Queries** - Run reactively against and across collections with support for joins, filters and aggregates. Powered by differential dataflow, query results update incrementally without re-running the whole query.
175​
176**Transactional Optimistic Mutations** - Batch and stage local changes across collections with immediate application of local optimistic updates. Sync transactions to the backend with automatic rollbacks and management of optimistic state.
177​
178#### Usage with Query Collections
179​
180This example uses Query Collections for server-state synchronization with tRPC:
181​
182```tsx
183import { createCollection } from '@tanstack/react-db'
184import { queryCollectionOptions } from '@tanstack/query-db-collection'
185import { QueryClient } from '@tanstack/query-core'
186​
187const queryClient = new QueryClient()
188​
189export const todoCollection = createCollection(
190 queryCollectionOptions<Todo>({
191 id: 'todos',
192 queryKey: ['todos'],
193 queryFn: async () => {
194 const todos = await trpc.todos.getAll.query()
195 return todos.map((todo) => ({
196 ...todo,
197 created_at: new Date(todo.created_at),
198 updated_at: new Date(todo.updated_at),
199 }))
200 },
201 queryClient,
202 schema: todoSchema,
203 getKey: (item) => item.id,
204 onInsert: async ({ transaction }) => {
205 const { modified: newTodo } = transaction.mutations[0]
206 const result = await trpc.todos.create.mutate({
207 text: newTodo.text,
208 completed: newTodo.completed,
209 project_id: newTodo.project_id,
210 })
211 return { txid: result.txid }
212 },
213 // You can also implement onUpdate, onDelete as needed
214 })
216```
217​
218Apply mutations with local optimistic state that automatically syncs:
219​
220```tsx
221const AddTodo = () => {
222 return (
223 <Button
224 onClick={() =>
225 todoCollection.insert({
226 id: crypto.randomUUID(),
227 text: '🔥 Make app faster',
228 completed: false,
229 })
230 }
231 />
232 )
234```
235​
236#### Live Queries with Cross-Collection Joins
237​
238Use live queries to read data reactively across collections:
239​
240```tsx
241import { useLiveQuery } from '@tanstack/react-db'
242​
243const Todos = () => {
244 // Read data using live queries with cross-collection joins
245 const { data: todos } = useLiveQuery((query) =>
246 query
247 .from({ t: todoCollection })
248 .join({
249 type: 'inner',
250 from: { l: listCollection },
251 on: [`@l.id`, `=`, `@t.list_id`],
252 })
253 .where('@l.active', '=', true)
254 .select('@t.id', '@t.text', '@t.status', '@l.name')
255 )
256​
257 return (
258 <ul>
259 {todos.map((todo) => (
260 <li key={todo.id}>
261 {todo.text} - {todo.name}
262 </li>
263 ))}
264 </ul>
265 )
267```
268​
269This pattern provides blazing fast, cross-collection live queries and local optimistic mutations with automatically managed optimistic state, all synced with your backend via tRPC.
270​
271You can learn more about TanStack DB in the [TanStack DB documentation](https://tanstack.com/db/latest/docs/overview).
272​
273# Learn More
274​
275You can learn more about all of the offerings from TanStack in the [TanStack documentation](https://tanstack.com).