Open History to see the last commit
1Welcome to your new TanStack app!
2
3# Getting Started
4
5To run this application:
6
7```bash
8npm install
9npm run dev
10```
11
12# Building For Production
13
14To build this application for production:
15
16```bash
17npm run build
18```
19
20## Testing
21
22This project uses [Vitest](https://vitest.dev/) for testing. You can run the tests with:
23
24```bash
25npm run test
26```
27
28## Styling
29
30This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
31
32
33
34## Shadcn
35
36Add components using the latest version of [Shadcn](https://ui.shadcn.com/).
37
38```bash
39pnpm dlx shadcn@latest add button
40```
41
42
43
44## Routing
45This 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`.
46
47### Adding A Route
48
49To add a new route to your application just add another a new file in the `./src/routes` directory.
50
51TanStack will automatically generate the content of the route file for you.
52
53Now that you have two routes you can use a `Link` component to navigate between them.
54
55### Adding Links
56
57To use SPA (Single Page Application) navigation you will need to import the `Link` component from `@tanstack/react-router`.
58
59```tsx
60import { Link } from "@tanstack/react-router";
61```
62
63Then anywhere in your JSX you can use it like so:
64
65```tsx
66<Link to="/about">About</Link>
67```
68
69This will create a link that will navigate to the `/about` route.
70
71More information on the `Link` component can be found in the [Link documentation](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
72
73### Using A Layout
74
75In 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.
76
77Here is an example layout that includes a header:
78
79```tsx
80import { Outlet, createRootRoute } from '@tanstack/react-router'
81import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
82
83import { Link } from "@tanstack/react-router";
84
85export const Route = createRootRoute({
86 component: () => (
87 <>
88 <header>
89 <nav>
90 <Link to="/">Home</Link>
91 <Link to="/about">About</Link>
92 </nav>
93 </header>
94 <Outlet />
95 <TanStackRouterDevtools />
96 </>
97 ),
98})
99```
100
101The `<TanStackRouterDevtools />` component is not required so you can remove it if you don't want it in your layout.
102
103More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
104
105
106## Data Fetching
107
108There are multiple ways to fetch data in your application. You can use TanStack Query 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.
109
110For example:
111
112```tsx
113const peopleRoute = createRoute({
114 getParentRoute: () => rootRoute,
115 path: "/people",
116 loader: async () => {
117 const response = await fetch("https://swapi.dev/api/people");
118 return response.json() as Promise<{
119 results: {
120 name: string;
121 }[];
122 }>;
123 },
124 component: () => {
125 const data = peopleRoute.useLoaderData();
126 return (
127 <ul>
128 {data.results.map((person) => (
129 <li key={person.name}>{person.name}</li>
130 ))}
131 </ul>
132 );
133 },
134});
135```
136
137Loaders 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).
138
139### React-Query
140
141React-Query is an excellent addition or alternative to route loading and integrating it into you application is a breeze.
142
143First add your dependencies:
144
145```bash
146npm install @tanstack/react-query @tanstack/react-query-devtools
147```
148
149Next we'll need to create a query client and provider. We recommend putting those in `main.tsx`.
150
151```tsx
152import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
153
154// ...
155
156const queryClient = new QueryClient();
157
158// ...
159
160if (!rootElement.innerHTML) {
161 const root = ReactDOM.createRoot(rootElement);
162
163 root.render(
164 <QueryClientProvider client={queryClient}>
165 <RouterProvider router={router} />
166 </QueryClientProvider>
167 );
168}
169```
170
171You can also add TanStack Query Devtools to the root route (optional).
172
173```tsx
174import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
175
176const rootRoute = createRootRoute({
177 component: () => (
178 <>
179 <Outlet />
180 <ReactQueryDevtools buttonPosition="top-right" />
181 <TanStackRouterDevtools />
182 </>
183 ),
184});
185```
186
187Now you can use `useQuery` to fetch your data.
188
189```tsx
190import { useQuery } from "@tanstack/react-query";
191
192import "./App.css";
193
194function App() {
195 const { data } = useQuery({
196 queryKey: ["people"],
197 queryFn: () =>
198 fetch("https://swapi.dev/api/people")
199 .then((res) => res.json())
200 .then((data) => data.results as { name: string }[]),
201 initialData: [],
202 });
203
204 return (
205 <div>
206 <ul>
207 {data.map((person) => (
208 <li key={person.name}>{person.name}</li>
209 ))}
210 </ul>
211 </div>
212 );
213}
214
215export default App;
216```
217
218You can find out everything you need to know on how to use React-Query in the [React-Query documentation](https://tanstack.com/query/latest/docs/framework/react/overview).
219
220## State Management
221
222Another common requirement for React applications is state management. There are many options for state management in React. TanStack Store provides a great starting point for your project.
223
224First you need to add TanStack Store as a dependency:
225
226```bash
227npm install @tanstack/store
228```
229
230Now let's create a simple counter in the `src/App.tsx` file as a demonstration.
231
232```tsx
233import { useStore } from "@tanstack/react-store";
234import { Store } from "@tanstack/store";
235import "./App.css";
236
237const countStore = new Store(0);
238
239function App() {
240 const count = useStore(countStore);
241 return (
242 <div>
243 <button onClick={() => countStore.setState((n) => n + 1)}>
244 Increment - {count}
245 </button>
246 </div>
247 );
248}
249
250export default App;
251```
252
253One of the many nice features of TanStack Store is the ability to derive state from other state. That derived state will update when the base state updates.
254
255Let's check this out by doubling the count using derived state.
256
257```tsx
258import { useStore } from "@tanstack/react-store";
259import { Store, Derived } from "@tanstack/store";
260import "./App.css";
261
262const countStore = new Store(0);
263
264const doubledStore = new Derived({
265 fn: () => countStore.state * 2,
266 deps: [countStore],
267});
268doubledStore.mount();
269
270function App() {
271 const count = useStore(countStore);
272 const doubledCount = useStore(doubledStore);
273
274 return (
275 <div>
276 <button onClick={() => countStore.setState((n) => n + 1)}>
277 Increment - {count}
278 </button>
279 <div>Doubled - {doubledCount}</div>
280 </div>
281 );
282}
283
284export default App;
285```
286
287We use the `Derived` class to create a new store that is derived from another store. The `Derived` class has a `mount` method that will start the derived store updating.
288
289Once we've created the derived store we can use it in the `App` component just like we would any other store using the `useStore` hook.
290
291You can find out everything you need to know on how to use TanStack Store in the [TanStack Store documentation](https://tanstack.com/store/latest).
292
293# Demo files
294
295Files prefixed with `demo` can be safely deleted. They are there to provide a starting point for you to play around with the features you've installed.
296
297# Learn More
298
299You can learn more about all of the offerings from TanStack in the [TanStack documentation](https://tanstack.com).