Umgebungsfunktionen | TanStack Start React Docs

Was sind Umgebungsfunktionen?

Umgebungsfunktionen sind Dienstprogramme, die entwickelt wurden, um die Ausführung von Funktionen basierend auf der Laufzeitumgebung zu definieren und zu steuern – ob der Code auf dem Client oder auf dem Server ausgeführt wird. Diese Dienstprogramme helfen sicherzustellen, dass umgebungsspezifische Logik sicher und absichtlich ausgeführt wird, wodurch Laufzeitfehler vermieden und die Wartbarkeit in Fullstack- oder isomorphen Anwendungen verbessert wird.

Start stellt drei Kernumgebungsfunktionen zur Verfügung

createIsomorphicFn: Erstellt eine einzelne Funktion, die sich sowohl an Client- als auch an Serverumgebungen anpasst.
serverOnly: Stellt sicher, dass eine Funktion nur auf dem Server ausgeführt werden kann.
clientOnly: Stellt sicher, dass eine Funktion nur auf dem Client ausgeführt werden kann.

Isomorphe Funktionen

Verwenden Sie createIsomorphicFn(), um Funktionen zu definieren, die sich je nach Aufruf auf dem Client oder dem Server unterschiedlich verhalten. Dies ist nützlich, um Logik sicher über Umgebungen hinweg zu teilen und umgebungsspezifisches Verhalten an geeignete Handler zu delegieren.

Vollständige Implementierung

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const getEnv = createIsomorphicFn()
  .server(() => 'server')
  .client(() => 'client')

const env = getEnv()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it returns `'client'`.

import { createIsomorphicFn } from '@tanstack/react-start'

const getEnv = createIsomorphicFn()
  .server(() => 'server')
  .client(() => 'client')

const env = getEnv()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it returns `'client'`.

Teilweise Implementierung (Server)

Hier ist ein Beispiel für createIsomorphicFn() mit nur Serverimplementierung

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const serverImplementationOnly = createIsomorphicFn().server(() => 'server')

const server = serverImplementationOnly()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it is no-op (returns `undefined`)

import { createIsomorphicFn } from '@tanstack/react-start'

const serverImplementationOnly = createIsomorphicFn().server(() => 'server')

const server = serverImplementationOnly()
// ℹ️ On the **server**, it returns `'server'`.
// ℹ️ On the **client**, it is no-op (returns `undefined`)

Teilweise Implementierung (Client)

Hier ist ein Beispiel für createIsomorphicFn() mit nur Clientimplementierung

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const clientImplementationOnly = createIsomorphicFn().client(() => 'client')

const client = clientImplementationOnly()
// ℹ️ On the **server**, it is no-op (returns `undefined`)
// ℹ️ On the **client**, it returns `'client'`.

import { createIsomorphicFn } from '@tanstack/react-start'

const clientImplementationOnly = createIsomorphicFn().client(() => 'client')

const client = clientImplementationOnly()
// ℹ️ On the **server**, it is no-op (returns `undefined`)
// ℹ️ On the **client**, it returns `'client'`.

Keine Implementierung

Hier ist ein Beispiel für createIsomorphicFn() ohne umgebungsspezifische Implementierung

tsx

import { createIsomorphicFn } from '@tanstack/react-start'

const noImplementation = createIsomorphicFn()

const noop = noImplementation()
// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`)

import { createIsomorphicFn } from '@tanstack/react-start'

const noImplementation = createIsomorphicFn()

const noop = noImplementation()
// ℹ️ On both **client** and **server**, it is no-op (returns `undefined`)

Was ist ein No-Op?

Ein No-Op (Kurzform für "no operation") ist eine Funktion, die bei Ausführung nichts tut – sie gibt einfach undefined zurück, ohne Operationen durchzuführen.

tsx

// basic no-op implementation
function noop() {}

// basic no-op implementation
function noop() {}

Nur-Umgebungsfunktionen

Die Helfer serverOnly und clientOnly erzwingen eine strikt umgebungsgebundene Ausführung. Sie stellen sicher, dass die dekorierte Funktion nur im richtigen Laufzeitkontext aufrufbar ist. Bei Missbrauch werfen sie aussagekräftige Laufzeitfehler, um unbeabsichtigte Logikausführungen zu verhindern.

serverOnly

tsx

import { serverOnly } from '@tanstack/react-start'

const foo = serverOnly(() => 'bar')

foo() // ✅ On server: returns "bar"
// ❌ On client: throws "serverOnly() functions can only be called on the server!"

import { serverOnly } from '@tanstack/react-start'

const foo = serverOnly(() => 'bar')

foo() // ✅ On server: returns "bar"
// ❌ On client: throws "serverOnly() functions can only be called on the server!"

clientOnly

tsx

import { clientOnly } from '@tanstack/react-start'

const foo = clientOnly(() => 'bar')

foo() // ✅ On client: returns "bar"
// ❌ On server: throws "clientOnly() functions can only be called on the client!"

import { clientOnly } from '@tanstack/react-start'

const foo = clientOnly(() => 'bar')

foo() // ✅ On client: returns "bar"
// ❌ On server: throws "clientOnly() functions can only be called on the client!"

Hinweis

Diese Funktionen sind nützlich für den API-Zugriff, das Lesen von Dateisystemen, die Verwendung von Browser-APIs oder andere Operationen, die außerhalb ihrer vorgesehenen Umgebung ungültig oder unsicher sind.

Tree Shaking

Umgebungsfunktionen werden basierend auf der Umgebung für jedes erzeugte Bundle "tree-shaken" (d.h. unnötiger Code wird entfernt).

Funktionen, die mit createIsomorphicFn() erstellt wurden, werden "tree-shaken". Der gesamte Code in .client() wird nicht in das Server-Bundle aufgenommen und umgekehrt.

Auf dem Server wird die Implementierung von clientOnly-Funktionen durch eine Funktion ersetzt, die einen Error auslöst. Das Gegenteil gilt für serverOnly-Funktionen auf dem Client.

Umgebungs-Funktionen