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

README.md

193 lines5.0 KB

1Welcome to your new TanStack Start 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### 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: `npm install @tailwindcss/vite tailwindcss -D`
40​
41​
42​
43## Routing
44​
45This project uses [TanStack Router](https://tanstack.com/router) with file-based routing. Routes are managed as files in `src/routes`.
46​
47### Adding A Route
48​
49To add a new route to your application just add 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 render `{children}` in the `shellComponent`.
76​
77Here is an example layout that includes a header:
78​
79```tsx
80import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
81​
82export const Route = createRootRoute({
83 head: () => ({
84 meta: [
85 { charSet: 'utf-8' },
86 { name: 'viewport', content: 'width=device-width, initial-scale=1' },
87 { title: 'My App' },
88 ],
89 }),
90 shellComponent: ({ children }) => (
91 <html lang="en">
92 <head>
93 <HeadContent />
94 </head>
95 <body>
96 <header>
97 <nav>
98 <Link to="/">Home</Link>
99 <Link to="/about">About</Link>
100 </nav>
101 </header>
102 {children}
103 <Scripts />
104 </body>
105 </html>
106 ),
107})
108```
109​
110More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
111​
112## Server Functions
113​
114TanStack Start provides server functions that allow you to write server-side code that seamlessly integrates with your client components.
115​
116```tsx
117import { createServerFn } from '@tanstack/react-start'
118​
119const getServerTime = createServerFn({
120 method: 'GET',
121}).handler(async () => {
122 return new Date().toISOString()
123})
124​
125// Use in a component
126function MyComponent() {
127 const [time, setTime] = useState('')
129 useEffect(() => {
130 getServerTime().then(setTime)
131 }, [])
133 return <div>Server time: {time}</div>
135```
136​
137## API Routes
138​
139You can create API routes by using the `server` property in your route definitions:
140​
141```tsx
142import { createFileRoute } from '@tanstack/react-router'
143import { json } from '@tanstack/react-start'
144​
145export const Route = createFileRoute('/api/hello')({
146 server: {
147 handlers: {
148 GET: () => json({ message: 'Hello, World!' }),
149 },
150 },
151})
152```
153​
154## Data Fetching
155​
156There 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.
157​
158For example:
159​
160```tsx
161import { createFileRoute } from '@tanstack/react-router'
162​
163export const Route = createFileRoute('/people')({
164 loader: async () => {
165 const response = await fetch('https://swapi.dev/api/people')
166 return response.json()
167 },
168 component: PeopleComponent,
169})
170​
171function PeopleComponent() {
172 const data = Route.useLoaderData()
173 return (
174 <ul>
175 {data.results.map((person) => (
176 <li key={person.name}>{person.name}</li>
177 ))}
178 </ul>
179 )
181```
182​
183Loaders 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).
184​
185# Demo files
186​
187Files 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.
188​
189# Learn More
190​
191You can learn more about all of the offerings from TanStack in the [TanStack documentation](https://tanstack.com).
192​
193For TanStack Start specific documentation, visit [TanStack Start](https://tanstack.com/start).