Open History to see the last commit
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 })
215)
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 )
233}
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 )
266}
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).