1Welcome to your new TanStack Start app!
2
3# Getting Started
4
5To run this application:
6
7```bash
8bun install
9bun --bun run dev
10```
11
12# Building For Production
13
14To build this application for production:
15
16```bash
17bun --bun 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
25bun --bun run test
26```
27
28## Styling
29
30This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
31
32### Removing Tailwind CSS
33
34If you prefer not to use Tailwind CSS:
35
361. Remove the demo pages in `src/routes/demo/`
372. Replace the Tailwind import in `src/styles.css` with your own styles
383. Remove `tailwindcss()` from the plugins array in `vite.config.ts`
394. Uninstall the packages: `bun install @tailwindcss/vite tailwindcss -D`
40
41## Routing
42
43This project uses [TanStack Router](https://tanstack.com/router) with file-based routing. Routes are managed as files in `src/routes`.
44
45### Adding A Route
46
47To add a new route to your application just add a new file in the `./src/routes` directory.
48
49TanStack will automatically generate the content of the route file for you.
50
51Now that you have two routes you can use a `Link` component to navigate between them.
52
53### Adding Links
54
55To use SPA (Single Page Application) navigation you will need to import the `Link` component from `@tanstack/react-router`.
56
57```tsx
58import { Link } from "@tanstack/react-router";
59```
60
61Then anywhere in your JSX you can use it like so:
62
63```tsx
64<Link to="/about">About</Link>
65```
66
67This will create a link that will navigate to the `/about` route.
68
69More information on the `Link` component can be found in the [Link documentation](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
70
71### Using A Layout
72
73In 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 render `{children}` in the `shellComponent`.
74
75Here is an example layout that includes a header:
76
77```tsx
78import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
79
80export const Route = createRootRoute({
81 head: () => ({
82 meta: [
83 { charSet: "utf-8" },
84 { name: "viewport", content: "width=device-width, initial-scale=1" },
85 { title: "My App" },
86 ],
87 }),
88 shellComponent: ({ children }) => (
89 <html lang="en">
90 <head>
91 <HeadContent />
92 </head>
93 <body>
94 <header>
95 <nav>
96 <Link to="/">Home</Link>
97 <Link to="/about">About</Link>
98 </nav>
99 </header>
100 {children}
101 <Scripts />
102 </body>
103 </html>
104 ),
105});
106```
107
108More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
109
110## Server Functions
111
112TanStack Start provides server functions that allow you to write server-side code that seamlessly integrates with your client components.
113
114```tsx
115import { createServerFn } from "@tanstack/react-start";
116
117const getServerTime = createServerFn({
118 method: "GET",
119}).handler(async () => {
120 return new Date().toISOString();
121});
122
123// Use in a component
124function MyComponent() {
125 const [time, setTime] = useState("");
126
127 useEffect(() => {
128 getServerTime().then(setTime);
129 }, []);
130
131 return <div>Server time: {time}</div>;
132}
133```
134
135## API Routes
136
137You can create API routes by using the `server` property in your route definitions:
138
139```tsx
140import { createFileRoute } from "@tanstack/react-router";
141import { json } from "@tanstack/react-start";
142
143export const Route = createFileRoute("/api/hello")({
144 server: {
145 handlers: {
146 GET: () => json({ message: "Hello, World!" }),
147 },
148 },
149});
150```
151
152## Data Fetching
153
154There 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.
155
156For example:
157
158```tsx
159import { createFileRoute } from "@tanstack/react-router";
160
161export const Route = createFileRoute("/people")({
162 loader: async () => {
163 const response = await fetch("https://swapi.dev/api/people");
164 return response.json();
165 },
166 component: PeopleComponent,
167});
168
169function PeopleComponent() {
170 const data = Route.useLoaderData();
171 return (
172 <ul>
173 {data.results.map((person) => (
174 <li key={person.name}>{person.name}</li>
175 ))}
176 </ul>
177 );
178}
179```
180
181Loaders 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).
182
183# Demo files
184
185Files 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.
186
187# Learn More
188
189You can learn more about all of the offerings from TanStack in the [TanStack documentation](https://tanstack.com).
190
191For TanStack Start specific documentation, visit [TanStack Start](https://tanstack.com/start).