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

environment-functions.md

123 lines4.2 KB

1---
2id: environment-functions
3title: Environment Functions
4---
5​
6## What Are Environment Functions?
7​
8Environment 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​
10Start provides three core environment functions:
11​
12- `createIsomorphicFn`: Compose a single function that adapts to both client and server environments.
13- `createServerOnlyFn`: Create a function that can only run on the server.
14- `createClientOnlyFn`: Create a function that can only run on the client.
15​
16---
17​
18## Isomorphic Functions
19​
20Use `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
25import { createIsomorphicFn } from '@tanstack/react-start'
26​
27const getEnv = createIsomorphicFn()
28 .server(() => 'server')
29 .client(() => 'client')
30​
31const env = getEnv()
32// ℹ️ On the **server**, it returns `'server'`.
33// ℹ️ On the **client**, it returns `'client'`.
34```
35​
36### Partial Implementation (Server)
37​
38Here is an example of `createIsomorphicFn()` with only server implementation:
39​
40```tsx
41import { createIsomorphicFn } from '@tanstack/react-start'
42​
43const serverImplementationOnly = createIsomorphicFn().server(() => 'server')
44​
45const 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​
52Here is an example of `createIsomorphicFn()` with only client implementation:
53​
54```tsx
55import { createIsomorphicFn } from '@tanstack/react-start'
56​
57const clientImplementationOnly = createIsomorphicFn().client(() => 'client')
58​
59const 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​
66Here is an example of `createIsomorphicFn()` without any environment specific implementation:
67​
68```tsx
69import { createIsomorphicFn } from '@tanstack/react-start'
70​
71const noImplementation = createIsomorphicFn()
72​
73const noop = noImplementation()
74// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`)
75```
76​
77#### What is a no-op?
78​
79A 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
83function noop() {}
84```
85​
86---
87​
88## `env`Only Functions
89​
90The `createServerOnlyFn` and `createClientOnlyFn` helpers enforce strict environment-bound execution. They ensure the returned function is only callable in the correct runtime context. If misused, they throw descriptive runtime errors to prevent unintentional logic execution.
91​
92### `createServerOnlyFn`
93​
94```tsx
95import { createServerOnlyFn } from '@tanstack/react-start'
96​
97const foo = createServerOnlyFn(() => 'bar')
98​
99foo() // ✅ On server: returns "bar"
100// ❌ On client: throws "createServerOnlyFn() functions can only be called on the server!"
101```
102​
103### `createClientOnlyFn`
104​
105```tsx
106import { createClientOnlyFn } from '@tanstack/react-start'
107​
108const foo = createClientOnlyFn(() => 'bar')
109​
110foo() // ✅ On client: returns "bar"
111// ❌ On server: throws "createClientOnlyFn() 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​
119Environment functions are tree-shaken based on the environment for each bundle produced.
120​
121Functions created using `createIsomorphicFn()` are tree-shaken. All codes inside `.client()` are not included in server bundle, and vice-versa.
122​
123On the server, functions created using `createClientOnlyFn()` are replaced with a function that throws an `Error` on the server. The reverse is true for `createServerOnlyFn` functions on the client.