Skip to content

Commit 74a3a06

Browse files
SeanCassiereSeanCassiere
authoredFeb 25, 2025··
refactor: move routing documentation into its own section (#3567)
·
v1.116.2v1.111.11
1 parent 6279354 commit 74a3a06

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1061
-793
lines changed
 

Diff for: ‎docs/router/api/file-based-routing.md

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: File-Based Routing API Reference
3+
---
4+
5+
> [!IMPORTANT]
6+
> Do not set the `routeFilePrefix`, `routeFileIgnorePrefix`, or `routeFileIgnorePattern` options, to match any of the tokens used in the [file-naming conventions](#file-naming-conventions) section.
7+
8+
- **`routeFilePrefix`**
9+
- (Optional) If set, only route files and directories that start with this string will be considered for routing.
10+
- **`routeFileIgnorePrefix`**
11+
- (Optional, **Defaults to `-`**) Route files and directories that start with this string will be ignored. By default this is set to `-` to allow for the use of directories to house related files that do not contain any route files.
12+
- **`routeFileIgnorePattern`**
13+
- (Optional) Ignore specific files and directories in the route directory. It can be used in regular expression format. For example, `.((css|const).ts)|test-page` will ignore files / directories with names containing `.css.ts`, `.const.ts` or `test-page`.
14+
- **`indexToken`**
15+
- (Optional, **Defaults to `'index'`**) allows to customize the `index` Token [file naming convention](#file-naming-conventions).
16+
- **`routeToken`**
17+
- (Optional, **Defaults to `'route'`**) allows to customize the `route` Token [file naming convention](#file-naming-conventions).
18+
- **`routesDirectory`**
19+
- (Required) The directory containing the routes relative to the cwd.
20+
- **`generatedRouteTree`**
21+
- (Required) The path to the file where the generated route tree will be saved, relative to the cwd.
22+
- **`autoCodeSplitting`**
23+
24+
- (Optional, **Defaults to `false`**)
25+
- If set to `true`, all non-critical route configuration items will be automatically code-split.
26+
- See the [using automatic code-splitting](./code-splitting.md#using-automatic-code-splitting) guide.
27+
28+
- **`quoteStyle`**
29+
- (Optional, **Defaults to `single`**) whether to use `single` or `double` quotes when formatting the generated files.
30+
- **`semicolons`**
31+
- (Optional, **Defaults to `false`**) whether to use semicolons in the generated files.
32+
- **`apiBase`**
33+
- (Optional) The base path for API routes. Defaults to `/api`.
34+
- This option is reserved for future use by the TanStack Start for API routes.
35+
- **`disableTypes`**
36+
- (Optional, **Defaults to `false`**) whether to disable generating types for the route tree
37+
- If set to `true`, the generated route tree will not include any types.
38+
- If set to `true` and the `generatedRouteTree` file ends with `.ts` or `.tsx`, the generated route tree will be written as a `.js` file instead.
39+
- **`addExtensions`**
40+
- (Optional, **Defaults to `false`**) add file extensions to the route names in the generated route tree
41+
- **`disableLogging`**
42+
- (Optional, **Defaults to `false`**) disables logging for the route generation process
43+
- **`routeTreeFileHeader`**
44+
45+
- (Optional) An array of strings to prepend to the generated route tree file content.
46+
- Default:
47+
- ```
48+
[
49+
'/* eslint-disable */',
50+
'// @ts-nocheck',
51+
'// noinspection JSUnusedGlobalSymbols'
52+
]
53+
```
54+
55+
- **`routeTreeFileFooter`**
56+
- (Optional) An array of strings to append to the generated route tree file content.
57+
- Default: `[]`
58+
- **`disableManifestGeneration`**
59+
- (Optional, **Defaults to `false`**) disables generating the route tree manifest
60+
61+
## Route Inclusion / Exclusion
62+
63+
Via the `routeFilePrefix` and `routeFileIgnorePrefix` options, the CLI can be configured to only include files and directories that start with a specific prefix, or to ignore files and directories that start with a specific prefix. This is especially useful when mixing non-route files with route files in the same directory, or when using a flat structure and wanting to exclude certain files from routing.
64+
65+
### Route Inclusion Example
66+
67+
To only consider files and directories that start with `~` for routing, the following configuration can be used:
68+
69+
> 🧠 A prefix of `~` is generally recommended when using this option. Not only is this symbol typically associated with the home-folder navigation in unix-based systems, but it is also a valid character for use in filenames and urls that will typically force the file to the top of a directory for easier visual indication of routes.
70+
71+
```json
72+
{
73+
"routeFilePrefix": "~",
74+
"routesDirectory": "./src/routes",
75+
"generatedRouteTree": "./src/routeTree.gen.ts"
76+
}
77+
```
78+
79+
With this configuration, the `Posts.tsx`, `Post.tsx`, and `PostEditor.tsx` files will be ignored during route generation.
80+
81+
```
82+
~__root.tsx
83+
~posts.tsx
84+
~posts
85+
~index.tsx
86+
~$postId.tsx
87+
~$postId
88+
~edit.tsx
89+
PostEditor.tsx
90+
Post.tsx
91+
Posts.tsx
92+
```
93+
94+
It's also common to use directories to house related files that do not contain any route files:
95+
96+
```
97+
~__root.tsx
98+
~posts.tsx
99+
~posts
100+
~index.tsx
101+
~$postId.tsx
102+
~$postId
103+
~edit.tsx
104+
components
105+
PostEditor.tsx
106+
components
107+
Post.tsx
108+
components
109+
Posts.tsx
110+
utils
111+
Posts.tsx
112+
```
113+
114+
### Route Exclusion Example
115+
116+
To ignore files and directories that start with `-` for routing, the following configuration can be used:
117+
118+
> 🧠 A prefix of `-` is generally recommended when using this option since the minus symbol is typically associated with removal or exclusion.
119+
120+
```json
121+
{
122+
"routeFileIgnorePrefix": "-",
123+
"routesDirectory": "./src/routes",
124+
"generatedRouteTree": "./src/routeTree.gen.ts"
125+
}
126+
```
127+
128+
With this configuration, the `Posts.tsx`, `Post.tsx`, and `PostEditor.tsx` files will be ignored during route generation.
129+
130+
```
131+
__root.tsx
132+
posts.tsx
133+
posts
134+
index.tsx
135+
$postId.tsx
136+
$postId
137+
edit.tsx
138+
-PostEditor.tsx
139+
-Post.tsx
140+
-Posts.tsx
141+
```
142+
143+
It's also common to use ignored directories to house related files that do not contain any route files:
144+
145+
```
146+
__root.tsx
147+
posts.tsx
148+
posts
149+
index.tsx
150+
$postId.tsx
151+
$postId
152+
edit.tsx
153+
-components
154+
PostEditor.tsx
155+
-components
156+
Post.tsx
157+
-components
158+
Posts.tsx
159+
-utils
160+
Posts.tsx
161+
```

Diff for: ‎docs/router/config.json

+100-43
Original file line numberDiff line numberDiff line change
@@ -75,47 +75,123 @@
7575
]
7676
},
7777
{
78-
"label": "Guide",
78+
"label": "Routing",
7979
"children": [],
8080
"frameworks": [
8181
{
8282
"label": "react",
8383
"children": [
8484
{
85-
"label": "Route Trees & Nesting",
86-
"to": "framework/react/guide/route-trees"
85+
"label": "Routing Concepts",
86+
"to": "framework/react/routing/routing-concepts"
8787
},
8888
{
89-
"label": "Routing Concepts",
90-
"to": "framework/react/guide/routing-concepts"
89+
"label": "Route Trees",
90+
"to": "framework/react/routing/route-trees"
91+
},
92+
{
93+
"label": "Route Matching",
94+
"to": "framework/react/routing/route-matching"
9195
},
9296
{
9397
"label": "File-Based Routing",
94-
"to": "framework/react/guide/file-based-routing"
98+
"to": "framework/react/routing/file-based-routing"
9599
},
96100
{
97-
"label": "Code Splitting",
98-
"to": "framework/react/guide/code-splitting"
101+
"label": "Virtual File Routes",
102+
"to": "framework/react/routing/virtual-file-routes"
99103
},
100104
{
101-
"label": "Automatic Code Splitting",
102-
"to": "framework/react/guide/automatic-code-splitting"
105+
"label": "Code-Based Routing",
106+
"to": "framework/react/routing/code-based-routing"
103107
},
104108
{
105-
"label": "Virtual File Routes",
106-
"to": "framework/react/guide/virtual-file-routes"
109+
"label": "Installation with Vite",
110+
"to": "framework/react/routing/installation-with-vite"
107111
},
108112
{
109-
"label": "Code Based Routing",
110-
"to": "framework/react/guide/code-based-routing"
113+
"label": "Installation with Rspack/Rsbuild",
114+
"to": "framework/react/routing/installation-with-rspack"
111115
},
112116
{
113-
"label": "Creating a Router",
114-
"to": "framework/react/guide/creating-a-router"
117+
"label": "Installation with Webpack",
118+
"to": "framework/react/routing/installation-with-webpack"
119+
},
120+
{
121+
"label": "Installation with Esbuild",
122+
"to": "framework/react/routing/installation-with-esbuild"
123+
},
124+
{
125+
"label": "Installation with the Router CLI",
126+
"to": "framework/react/routing/installation-with-router-cli"
127+
},
128+
{
129+
"label": "File Naming Conventions",
130+
"to": "framework/react/routing/file-naming-conventions"
131+
}
132+
]
133+
},
134+
{
135+
"label": "solid",
136+
"children": [
137+
{
138+
"label": "Routing Concepts",
139+
"to": "framework/solid/routing/routing-concepts"
140+
},
141+
{
142+
"label": "Route Trees",
143+
"to": "framework/solid/routing/route-trees"
115144
},
116145
{
117146
"label": "Route Matching",
118-
"to": "framework/react/guide/route-matching"
147+
"to": "framework/solid/routing/route-matching"
148+
},
149+
{
150+
"label": "File-Based Routing",
151+
"to": "framework/solid/routing/file-based-routing"
152+
},
153+
{
154+
"label": "Virtual File Routes",
155+
"to": "framework/solid/routing/virtual-file-routes"
156+
},
157+
{
158+
"label": "Code-Based Routing",
159+
"to": "framework/solid/routing/code-based-routing"
160+
},
161+
{
162+
"label": "Installation with Vite",
163+
"to": "framework/solid/routing/installation-with-vite"
164+
},
165+
{
166+
"label": "Installation with the Router CLI",
167+
"to": "framework/solid/routing/installation-with-router-cli"
168+
},
169+
{
170+
"label": "File Naming Conventions",
171+
"to": "framework/solid/routing/file-naming-conventions"
172+
}
173+
]
174+
}
175+
]
176+
},
177+
{
178+
"label": "Guide",
179+
"children": [],
180+
"frameworks": [
181+
{
182+
"label": "react",
183+
"children": [
184+
{
185+
"label": "Code Splitting",
186+
"to": "framework/react/guide/code-splitting"
187+
},
188+
{
189+
"label": "Automatic Code Splitting",
190+
"to": "framework/react/guide/automatic-code-splitting"
191+
},
192+
{
193+
"label": "Creating a Router",
194+
"to": "framework/react/guide/creating-a-router"
119195
},
120196
{
121197
"label": "Outlets",
@@ -222,18 +298,6 @@
222298
{
223299
"label": "solid",
224300
"children": [
225-
{
226-
"label": "Route Trees & Nesting",
227-
"to": "framework/solid/guide/route-trees"
228-
},
229-
{
230-
"label": "Routing Concepts",
231-
"to": "framework/solid/guide/routing-concepts"
232-
},
233-
{
234-
"label": "File-Based Routing",
235-
"to": "framework/solid/guide/file-based-routing"
236-
},
237301
{
238302
"label": "Code Splitting",
239303
"to": "framework/solid/guide/code-splitting"
@@ -242,22 +306,10 @@
242306
"label": "Automatic Code Splitting",
243307
"to": "framework/solid/guide/automatic-code-splitting"
244308
},
245-
{
246-
"label": "Virtual File Routes",
247-
"to": "framework/solid/guide/virtual-file-routes"
248-
},
249-
{
250-
"label": "Code Based Routing",
251-
"to": "framework/solid/guide/code-based-routing"
252-
},
253309
{
254310
"label": "Creating a Router",
255311
"to": "framework/solid/guide/creating-a-router"
256312
},
257-
{
258-
"label": "Route Matching",
259-
"to": "framework/solid/guide/route-matching"
260-
},
261313
{
262314
"label": "Outlets",
263315
"to": "framework/solid/guide/outlets"
@@ -356,13 +408,18 @@
356408
},
357409
{
358410
"label": "API",
359-
"children": [],
411+
"children": [
412+
{
413+
"label": "File-Based Routing",
414+
"to": "api/file-based-routing"
415+
}
416+
],
360417
"frameworks": [
361418
{
362419
"label": "react",
363420
"children": [
364421
{
365-
"label": "Reference",
422+
"label": "Router",
366423
"to": "framework/react/api/router"
367424
}
368425
]

0 commit comments

Comments
 (0)
Please sign in to comment.