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

README.md

299 lines7.6 KB

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 );
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 );
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 );
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 );
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).