Umgebungsfunktionen | TanStack Start Solid Docs

Was sind Umgebungsfunktionen?

Umgebungsfunktionen sind Dienstprogramme, die dazu dienen, die Ausführung von Funktionen basierend auf der Laufzeitumgebung zu definieren und zu steuern – egal ob der Code auf dem Client oder dem Server ausgeführt wird. Diese Dienstprogramme stellen sicher, dass umgebungsspezifische Logik sicher und gezielt ausgeführt wird, was Laufzeitfehler verhindert und die Wartbarkeit in Fullstack- oder isomeren Anwendungen verbessert.

Start bietet drei Kern-Umgebungsfunktionen

createIsomorphicFn: Bildet eine einzelne Funktion, die sich an Client- und 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/solid-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/solid-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 Server-Implementierung

tsx

import { createIsomorphicFn } from '@tanstack/solid-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/solid-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 Client-Implementierung

tsx

import { createIsomorphicFn } from '@tanstack/solid-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/solid-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/solid-start'

const noImplementation = createIsomorphicFn()

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

import { createIsomorphicFn } from '@tanstack/solid-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" / "Keine Operation") ist eine Funktion, die bei der Ausführung nichts tut – sie gibt einfach undefined zurück, ohne Aktionen auszuführen.

tsx

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

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

envNur Funktionen

Die Helfer serverOnly und clientOnly erzwingen eine strenge, umgebungsgebundene Ausführung. Sie stellen sicher, dass die dekorierte Funktion nur im richtigen Laufzeitkontext aufrufbar ist. Bei falscher Verwendung lösen sie aussagekräftige Laufzeitfehler aus, um unbeabsichtigte Logikausführungen zu verhindern.

serverOnly

tsx

import { serverOnly } from '@tanstack/solid-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/solid-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/solid-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/solid-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 beabsichtigten Umgebung ungültig oder unsicher sind.

Tree Shaking

Umgebungsfunktionen werden basierend auf der Umgebung für jedes erzeugte Bundle per Tree-Shaking entfernt.

Funktionen, die mit createIsomorphicFn() erstellt wurden, werden per Tree-Shaking entfernt. Jeglicher Code innerhalb von .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