Skip to content

Commit 028f0ab

Browse files
authored
Merge branch 'main' into refactor-router-core-before-load-skip-or-execute
2 parents 360177f + 741821b commit 028f0ab

183 files changed

Lines changed: 6303 additions & 660 deletions

File tree

Some content is hidden

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

‎CONTRIBUTING.md‎

Lines changed: 55 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,58 @@
2323
- `pnpm dev`
2424
- Make changes to the code
2525
- If you ran `pnpm dev` the dev watcher will automatically rebuild the code that has changed
26-
- Changes to the docs
27-
- Be sure that internal links are written always relative to `docs` folder.
28-
E.g. `./guide/data-loading`
26+
- Editing the docs locally and previewing the changes
27+
- The documentations for all the TanStack projects are hosted on [tanstack.com](https://tanstack.com), which is a TanStack Start application (https://github.com/TanStack/tanstack.com). You need to run this app locally to preview your changes in the `TanStack/router` docs.
28+
29+
> [!NOTE]
30+
> The website fetches the doc pages from GitHub in production, and searches for them at `../router/docs` in development. Your local clone of `TanStack/router` needs to be in the same directory as the local clone of `TanStack/tanstack.com`.
31+
32+
You can follow these steps to set up the docs for local development:
33+
34+
1. Make a new directory called `tanstack`.
35+
36+
```sh
37+
mkdir tanstack
38+
```
39+
40+
2. Enter that directory and clone the [`TanStack/router`](https://github.com/TanStack/router) and [`TanStack/tanstack.com`](https://github.com/TanStack/tanstack.com) repos.
41+
42+
```sh
43+
cd tanstack
44+
git clone [email protected]:TanStack/router.git
45+
# We probably don't need all the branches and commit history
46+
# from the `tanstack.com` repo, so let's just create a shallow
47+
# clone of the latest version of the `main` branch.
48+
# Read more about shallow clones here:
49+
# https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/#user-content-shallow-clones
50+
git clone [email protected]:TanStack/tanstack.com.git --depth=1 --single-branch --branch=main
51+
```
52+
53+
> [!NOTE]
54+
> Your `tanstack` directory should look like this:
55+
>
56+
> ```
57+
> tanstack/
58+
> |
59+
> +-- router/ (<-- this directory cannot be called anything else!)
60+
> |
61+
> +-- tanstack.com/
62+
> ```
63+
64+
3. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
65+
66+
```sh
67+
cd tanstack.com
68+
pnpm i
69+
# The app will run on https://localhost:3000 by default
70+
pnpm dev
71+
```
72+
73+
4. Now you can visit http://localhost:3000/router/latest/docs/framework/react/overview in the browser and see the changes you make in `tanstack/router/docs` there.
74+
75+
> [!WARNING]
76+
> You will need to update the `docs/(router or start)config.json` file (in `TanStack/router`) if you add a new documentation page!
77+
78+
You can see the whole process in the screen capture below:
79+
80+
https://github.com/fulopkovacs/form/assets/43729152/9d35a3c3-8153-4e74-9cb2-af275f7a269b

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ Enjoy this library? Try the entire [TanStack](https://tanstack.com)! [TanStack Q
4242
<div><a href="https://neon.tech?utm_source=tanstack">
4343
<img alt="Neon" src="https://raw.githubusercontent.com/tannerlinsley/files/master/partners/neon.svg" height="40"
4444
</a></div><br />
45+
<div><a href="https://www.prisma.io?utm_source=tanstack&via=tanstack">
46+
<img alt="Prisma" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/prisma-light.svg" height="40">
47+
</a></div><br />
4548
<div><a href="https://convex.dev?utm_source=tanstack">
4649
<img alt="Convex" src="https://raw.githubusercontent.com/tannerlinsley/files/master/partners/convex.svg" height="40"
4750
</a></div><br />

‎docs/router/framework/react/guide/external-data-loading.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Literally any library that **can return a promise and read/write data** can be i
3434

3535
## Using Loaders to ensure data is loaded
3636

37-
The easiest way to use integrate and external caching/data library into Router is to use `route.loader`s to ensure that the data required inside of a route has been loaded and is ready to be displayed.
37+
The easiest way to integrate external caching/data library into Router is to use `route.loader`s to ensure that the data required inside of a route has been loaded and is ready to be displayed.
3838

3939
> ⚠️ BUT WHY? It's very important to preload your critical render data in the loader for a few reasons:
4040
>
@@ -102,7 +102,7 @@ export const Route = createFileRoute('/posts')({
102102

103103
### Error handling with TanStack Query
104104

105-
When an error occurs while using `suspense` with `TanStack Query`, you'll need to let queries know that you want to try again when re-rendering. This can be done by using the `reset` function provided by the `useQueryErrorResetBoundary` hook. We can invoke this function in an effect as soon as the error component mounts. This will make sure that the query is reset and will try to fetch data again when the route component is rendered again. This will also cover cases where users navigate away from our route instead of clicking the `retry` button.
105+
When an error occurs while using `suspense` with `TanStack Query`, you need to let queries know that you want to try again when re-rendering. This can be done by using the `reset` function provided by the `useQueryErrorResetBoundary` hook. You can invoke this function in an effect as soon as the error component mounts. This will make sure that the query is reset and will try to fetch data again when the route component is rendered again. This will also cover cases where users navigate away from the route instead of clicking the `retry` button.
106106

107107
```tsx
108108
export const Route = createFileRoute('/')({

‎docs/router/framework/react/guide/navigation.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ type ToOptions<
2828
TTo extends string = '',
2929
> = {
3030
// `from` is an optional route ID or path. If it is not supplied, only absolute paths will be auto-completed and type-safe. It's common to supply the route.fullPath of the origin route you are rendering from for convenience. If you don't know the origin route, leave this empty and work with absolute paths or unsafe relative paths.
31-
from: string
31+
from?: string
3232
// `to` can be an absolute route path or a relative path from the `from` option to a valid route path. ⚠️ Do not interpolate path params, hash or search params into the `to` options. Use the `params`, `search`, and `hash` options instead.
3333
to: string
3434
// `params` is either an object of path params to interpolate into the `to` option or a function that supplies the previous params and allows you to return new ones. This is the only way to interpolate dynamic parameters into the final URL. Depending on the `from` and `to` route, you may need to supply none, some or all of the path params. TypeScript will notify you of the required params if there are any.
@@ -183,7 +183,7 @@ Keep in mind that normally dynamic segment params are `string` values, but they
183183

184184
By default, all links are absolute unless a `from` route path is provided. This means that the above link will always navigate to the `/about` route regardless of what route you are currently on.
185185

186-
If you want to make a link that is relative to the current route, you can provide a `from` route path:
186+
Relative links can be combined with a `from` route path. If a from route path isn't provided, relative paths default to the current active location.
187187

188188
```tsx
189189
const postIdRoute = createRoute({
@@ -201,9 +201,9 @@ As seen above, it's common to provide the `route.fullPath` as the `from` route p
201201

202202
### Special relative paths: `"."` and `".."`
203203

204-
Quite often you might want to reload the current location, for example, to rerun the loaders on the current and/or parent routes, or maybe there was a change in search parameters. This can be achieved by specifying a `to` route path of `"."` which will reload the current location. This is only applicable to the current location, and hence any `from` route path specified is ignored.
204+
Quite often you might want to reload the current location or another `from` path, for example, to rerun the loaders on the current and/or parent routes, or maybe navigate back to a parent route. This can be achieved by specifying a `to` route path of `"."` which will reload the current location or provided `from` path.
205205

206-
Another common need is to navigate one route back relative to the current location or some other matched route in the current tree. By specifying a `to` route path of `".."` navigation will be resolved to either the first parent route preceding the current location or, if specified, preceding the `"from"` route path.
206+
Another common need is to navigate one route back relative to the current location or another path. By specifying a `to` route path of `".."` navigation will be resolved to the first parent route preceding the current location.
207207

208208
```tsx
209209
export const Route = createFileRoute('/posts/$postId')({
@@ -214,7 +214,14 @@ function PostComponent() {
214214
return (
215215
<div>
216216
<Link to=".">Reload the current route of /posts/$postId</Link>
217-
<Link to="..">Navigate to /posts</Link>
217+
<Link to="..">Navigate back to /posts</Link>
218+
// the below are all equivalent
219+
<Link to="/posts">Navigate back to /posts</Link>
220+
<Link from="/posts" to=".">
221+
Navigate back to /posts
222+
</Link>
223+
// the below are all equivalent
224+
<Link to="/">Navigate to root</Link>
218225
<Link from="/posts" to="..">
219226
Navigate to root
220227
</Link>
@@ -660,13 +667,13 @@ With preloading enabled and relatively quick asynchronous route dependencies (if
660667

661668
What's even better is that by using a cache-first library like `@tanstack/query`, preloaded routes will stick around and be ready for a stale-while-revalidate experience if the user decides to navigate to the route later on.
662669

663-
### Link Preloading Timeout
670+
### Link Preloading Delay
664671

665-
Along with preloading is a configurable timeout which determines how long a user must hover over a link to trigger the intent-based preloading. The default timeout is 50 milliseconds, but you can change this by passing a `preloadTimeout` prop to the `Link` component with the number of milliseconds you'd like to wait:
672+
Along with preloading is a configurable delay which determines how long a user must hover over a link to trigger the intent-based preloading. The default delay is 50 milliseconds, but you can change this by passing a `preloadDelay` prop to the `Link` component with the number of milliseconds you'd like to wait:
666673

667674
```tsx
668675
const link = (
669-
<Link to="/blog/post/$postId" preload="intent" preloadTimeout={100}>
676+
<Link to="/blog/post/$postId" preload="intent" preloadDelay={100}>
670677
Blog Post
671678
</Link>
672679
)

‎docs/router/framework/react/installation.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,12 @@ vibe-rules install cursor
5151
```
5252

5353
But you can also use `windsurf`, `claude-code`, etc. Check the [vibe-rules](https://www.npmjs.com/package/vibe-rules) documentation for more information.
54+
55+
### Usage with yarn workspaces
56+
57+
When using yarn workspaces, you will need to add the following config to the `.yarnrc.yml` of the application using TanStack Router
58+
59+
```yml
60+
pnpFallbackMode: all
61+
pnpMode: loose
62+
```

‎docs/router/framework/react/quick-start.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -76,23 +76,23 @@ Create the following files:
7676
import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
7777
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
7878

79-
export const Route = createRootRoute({
80-
component: () => (
81-
<>
82-
<div className="p-2 flex gap-2">
83-
<Link to="/" className="[&.active]:font-bold">
84-
Home
85-
</Link>{' '}
86-
<Link to="/about" className="[&.active]:font-bold">
87-
About
88-
</Link>
89-
</div>
90-
<hr />
91-
<Outlet />
92-
<TanStackRouterDevtools />
93-
</>
94-
),
95-
})
79+
const RootLayout = () => (
80+
<>
81+
<div className="p-2 flex gap-2">
82+
<Link to="/" className="[&.active]:font-bold">
83+
Home
84+
</Link>{' '}
85+
<Link to="/about" className="[&.active]:font-bold">
86+
About
87+
</Link>
88+
</div>
89+
<hr />
90+
<Outlet />
91+
<TanStackRouterDevtools />
92+
</>
93+
)
94+
95+
export const Route = createRootRoute({ component: RootLayout })
9696
```
9797

9898
#### `src/routes/index.tsx`

‎docs/start/config.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@
4141
"label": "Static Server Functions",
4242
"to": "framework/react/static-server-functions"
4343
},
44+
{
45+
"label": "Environment Functions",
46+
"to": "framework/react/environment-functions"
47+
},
4448
{
4549
"label": "Middleware",
4650
"to": "framework/react/middleware"
@@ -122,6 +126,10 @@
122126
"label": "Static Server Functions",
123127
"to": "framework/solid/static-server-functions"
124128
},
129+
{
130+
"label": "Environment Functions",
131+
"to": "framework/solid/environment-functions"
132+
},
125133
{
126134
"label": "Middleware",
127135
"to": "framework/solid/middleware"

‎docs/start/framework/react/databases.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,28 @@ Convex's declarative data model and automatic conflict resolution ensure that yo
7979
- To learn more about Convex, visit the [Convex website](https://convex.dev?utm_source=tanstack)
8080
- To sign up, visit the [Convex dashboard](https://dashboard.convex.dev/signup?utm_source=tanstack)
8181

82+
## What is Prisma Postgres?
83+
84+
<a href="https://www.prisma.io?utm_source=tanstack&via=tanstack" alt="Prisma Logo">
85+
<picture>
86+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/prisma-dark.svg" width="280">
87+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/prisma-light.svg" width="280">
88+
<img alt="Prisma logo" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/prisma-light.svg" width="280">
89+
</picture>
90+
</a>
91+
92+
Instant Postgres, Zero Setup: Get a production-ready Postgres database in seconds, then dive straight back into code. We handle connections, scaling, and turning knobs so your flow never breaks. Blends perfectly with TanStack Start.
93+
94+
- Edge-optimized: Local region routing means lower latency and fewer hops. Even complex queries are one fast round trip.
95+
- Fits your stack: Works with your frameworks, libraries, and tools for a smooth DX.
96+
- Web UI: A hosted interface to inspect, manage, and query data with your team.
97+
- Auto-scaling: Grows from zero to millions of users without cold starts or manual tuning.
98+
- Unikernel isolation: Each DB runs as its own unikernel for security, speed, and efficiency.
99+
<br />
100+
<br />
101+
- To learn more about Prisma Postgres, visit the [Prisma website](https://www.prisma.io?utm_source=tanstack&via=tanstack)
102+
- To sign up, visit the [Prisma Console](https://console.prisma.io/sign-up?utm_source=tanstack&via=tanstack)
103+
82104
## Documentation & APIs
83105

84106
Documentation for integrating different databases with TanStack Start is coming soon! In the meantime, keep an eye on our examples and guide to learn how to fully leverage your data layer across your TanStack Start application.
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
id: environment-functions
3+
title: Environment Functions
4+
---
5+
6+
## What Are Environment Functions?
7+
8+
Environment functions are utilities designed to define and control function execution based on the runtime environment—whether the code is running on the client or the server. These utilities help ensure that environment-specific logic is executed safely and intentionally, preventing runtime errors and improving maintainability in fullstack or isomorphic applications.
9+
10+
Start provide three core environment functions:
11+
12+
- `createIsomorphicFn`: Compose a single function that adapts to both client and server environments.
13+
- `serverOnly`: Ensures a function can only run on the server.
14+
- `clientOnly`: Ensures a function can only run on the client.
15+
16+
---
17+
18+
## Isomorphic Functions
19+
20+
Use `createIsomorphicFn()` to define functions that behave differently depending on whether they are called on the client or the server. This is useful for safely sharing logic across environments while delegating environment-specific behavior to appropriate handlers.
21+
22+
### Complete Implementation
23+
24+
```tsx
25+
import { createIsomorphicFn } from '@tanstack/react-start'
26+
27+
const getEnv = createIsomorphicFn()
28+
.server(() => 'server')
29+
.client(() => 'client')
30+
31+
const env = getEnv()
32+
// ℹ️ On the **server**, it returns `'server'`.
33+
// ℹ️ On the **client**, it returns `'client'`.
34+
```
35+
36+
### Partial Implementation (Server)
37+
38+
Here is an example of `createIsomorphicFn()` with only server implementation:
39+
40+
```tsx
41+
import { createIsomorphicFn } from '@tanstack/react-start'
42+
43+
const serverImplementationOnly = createIsomorphicFn().server(() => 'server')
44+
45+
const server = serverImplementationOnly()
46+
// ℹ️ On the **server**, it returns `'server'`.
47+
// ℹ️ On the **client**, it is no-op (returns `undefined`)
48+
```
49+
50+
### Partial Implementation (Client)
51+
52+
Here is an example of `createIsomorphicFn()` with only client implementation:
53+
54+
```tsx
55+
import { createIsomorphicFn } from '@tanstack/react-start'
56+
57+
const clientImplementationOnly = createIsomorphicFn().client(() => 'client')
58+
59+
const client = clientImplementationOnly()
60+
// ℹ️ On the **server**, it is no-op (returns `undefined`)
61+
// ℹ️ On the **client**, it returns `'client'`.
62+
```
63+
64+
### No Implementation
65+
66+
Here is an example of `createIsomorphicFn()` without any environment specific implementation:
67+
68+
```tsx
69+
import { createIsomorphicFn } from '@tanstack/react-start'
70+
71+
const noImplementation = createIsomorphicFn()
72+
73+
const noop = noImplementation()
74+
// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`)
75+
```
76+
77+
#### What is a no-op?
78+
79+
A no-op (short for "no operation") is a function that does nothing when executed - it simply returns `undefined` without performing any operations.
80+
81+
```tsx
82+
// basic no-op implementation
83+
function noop() {}
84+
```
85+
86+
---
87+
88+
## `env`Only Functions
89+
90+
The `serverOnly` and `clientOnly` helpers enforce strict environment-bound execution. They ensure the decorated function is only callable in the correct runtime context. If misused, they throw descriptive runtime errors to prevent unintentional logic execution.
91+
92+
### `serverOnly`
93+
94+
```tsx
95+
import { serverOnly } from '@tanstack/react-start'
96+
97+
const foo = serverOnly(() => 'bar')
98+
99+
foo() // ✅ On server: returns "bar"
100+
// ❌ On client: throws "serverOnly() functions can only be called on the server!"
101+
```
102+
103+
### `clientOnly`
104+
105+
```tsx
106+
import { clientOnly } from '@tanstack/react-start'
107+
108+
const foo = clientOnly(() => 'bar')
109+
110+
foo() // ✅ On client: returns "bar"
111+
// ❌ On server: throws "clientOnly() functions can only be called on the client!"
112+
```
113+
114+
> [!NOTE]
115+
> These functions are useful for API access, filesystem reads, using browser APIs, or other operations that are invalid or insecure outside their intended environment.
116+
117+
## Tree Shaking
118+
119+
Environment functions are tree-shaken based on the environment for each bundle produced.
120+
121+
Functions created using `createIsomorphicFn()` are tree-shaken. All codes inside `.client()` are not included in server bundle, and vice-versa.
122+
123+
On the server, implementation of `clientOnly` functions are replaced with a function that throws an `Error`. The reverse is true for `serverOnly` functions on the client.

0 commit comments

Comments
 (0)