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

README.md.ejs

208 lines5.9 KB

1Welcome to your new TanStack Start app!
2​
3# Getting Started
4​
5To run this application:
6​
7```bash
8<%= packageManager %> install
9<%= getPackageManagerRunScript('dev') %>
10```
11​
12# Building For Production
13​
14To build this application for production:
15​
16```bash
17<%= getPackageManagerRunScript('build') %>
18```
19​
20## Testing
21​
22This project uses [Vitest](https://vitest.dev/) for testing. You can run the tests with:
23​
24```bash
25<%= getPackageManagerRunScript('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: `<%= getPackageManagerAddScript('@tailwindcss/vite tailwindcss', true) %>`
40<% if (addOnEnabled.biome || addOnEnabled.eslint) { %>
41## Linting & Formatting
42<% if (addOnEnabled.biome) { %>
43This project uses [Biome](https://biomejs.dev/) for linting and formatting. The following scripts are available:
44<% } %>
45<% if (addOnEnabled.eslint) { %>
46This project uses [eslint](https://eslint.org/) and [prettier](https://prettier.io/) for linting and formatting. Eslint is configured using [tanstack/eslint-config](https://tanstack.com/config/latest/docs/eslint). The following scripts are available:
47<% } %>
48```bash
49<%= getPackageManagerRunScript('lint') %>
50<%= getPackageManagerRunScript('format') %>
51<%= getPackageManagerRunScript('check') %>
52```
53<% } %>
54<% for(const addon of addOns.filter(addon => addon.readme)) { %>
55<%- addon.readmeIsEjs ? renderTemplate(addon.readme) : addon.readme %>
56<% } %>
57​
58## Routing
59​
60This project uses [TanStack Router](https://tanstack.com/router) with file-based routing. Routes are managed as files in `src/routes`.
61​
62### Adding A Route
63​
64To add a new route to your application just add a new file in the `./src/routes` directory.
65​
66TanStack will automatically generate the content of the route file for you.
67​
68Now that you have two routes you can use a `Link` component to navigate between them.
69​
70### Adding Links
71​
72To use SPA (Single Page Application) navigation you will need to import the `Link` component from `@tanstack/react-router`.
73​
74```tsx
75import { Link } from "@tanstack/react-router";
76```
77​
78Then anywhere in your JSX you can use it like so:
79​
80```tsx
81<Link to="/about">About</Link>
82```
83​
84This will create a link that will navigate to the `/about` route.
85​
86More information on the `Link` component can be found in the [Link documentation](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
87​
88### Using A Layout
89​
90In 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`.
91​
92Here is an example layout that includes a header:
93​
94```tsx
95import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
96​
97export const Route = createRootRoute({
98 head: () => ({
99 meta: [
100 { charSet: 'utf-8' },
101 { name: 'viewport', content: 'width=device-width, initial-scale=1' },
102 { title: 'My App' },
103 ],
104 }),
105 shellComponent: ({ children }) => (
106 <html lang="en">
107 <head>
108 <HeadContent />
109 </head>
110 <body>
111 <header>
112 <nav>
113 <Link to="/">Home</Link>
114 <Link to="/about">About</Link>
115 </nav>
116 </header>
117 {children}
118 <Scripts />
119 </body>
120 </html>
121 ),
122})
123```
124​
125More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
126​
127## Server Functions
128​
129TanStack Start provides server functions that allow you to write server-side code that seamlessly integrates with your client components.
130​
131```tsx
132import { createServerFn } from '@tanstack/react-start'
133​
134const getServerTime = createServerFn({
135 method: 'GET',
136}).handler(async () => {
137 return new Date().toISOString()
138})
139​
140// Use in a component
141function MyComponent() {
142 const [time, setTime] = useState('')
144 useEffect(() => {
145 getServerTime().then(setTime)
146 }, [])
148 return <div>Server time: {time}</div>
150```
151​
152## API Routes
153​
154You can create API routes by using the `server` property in your route definitions:
155​
156```tsx
157import { createFileRoute } from '@tanstack/react-router'
158import { json } from '@tanstack/react-start'
159​
160export const Route = createFileRoute('/api/hello')({
161 server: {
162 handlers: {
163 GET: () => json({ message: 'Hello, World!' }),
164 },
165 },
166})
167```
168​
169## Data Fetching
170​
171There 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.
172​
173For example:
174​
175```tsx
176import { createFileRoute } from '@tanstack/react-router'
177​
178export const Route = createFileRoute('/people')({
179 loader: async () => {
180 const response = await fetch('https://swapi.dev/api/people')
181 return response.json()
182 },
183 component: PeopleComponent,
184})
185​
186function PeopleComponent() {
187 const data = Route.useLoaderData()
188 return (
189 <ul>
190 {data.results.map((person) => (
191 <li key={person.name}>{person.name}</li>
192 ))}
193 </ul>
194 )
196```
197​
198Loaders 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).
199​
200# Demo files
201​
202Files 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.
203​
204# Learn More
205​
206You can learn more about all of the offerings from TanStack in the [TanStack documentation](https://tanstack.com).
207​
208For TanStack Start specific documentation, visit [TanStack Start](https://tanstack.com/start).