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

README.md.ejs

225 lines6.5 KB

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