본문으로 건너뛰기

환경 함수

환경 함수란 무엇인가요?​

환경 함수는 코드가 클라이언트에서 실행되는지 서버에서 실행되는지에 따라 런타임 환경을 기준으로 함수 실행을 정의하고 제어하도록 설계된 유틸리티입니다. 이러한 유틸리티는 환경별 로직이 안전하고 의도한 대로 실행되도록 하여 런타임 오류를 방지하고 풀스택 또는 동형 애플리케이션의 유지보수성을 높입니다.

Start는 세 가지 핵심 환경 함수를 제공합니다:

  • createIsomorphicFn: 클라이언트와 서버 환경 모두에 맞게 동작하는 단일 함수를 구성합니다.
  • createServerOnlyFn: 서버에서만 실행할 수 있는 함수를 생성합니다.
  • createClientOnlyFn: 클라이언트에서만 실행할 수 있는 함수를 생성합니다.

동형 함수​

createIsomorphicFn()을 사용하여 클라이언트에서 호출되는지 서버에서 호출되는지에 따라 다르게 동작하는 함수를 정의합니다. 환경별 동작을 적절한 핸들러에 위임하면서 여러 환경에서 로직을 안전하게 공유하는 데 유용합니다.

전체 구현​

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'`.

부분 구현(서버)​

다음은 서버 구현만 포함한 createIsomorphicFn()의 예시입니다:

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`)

부분 구현(클라이언트)​

다음은 클라이언트 구현만 포함한 createIsomorphicFn()의 예시입니다:

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'`.

구현 없음​

다음은 환경별 구현이 없는 createIsomorphicFn()의 예시입니다:

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

const noImplementation = createIsomorphicFn()

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

no-op이란 무엇인가요?​

no-op("no operation"의 줄임말)은 실행해도 아무 작업도 하지 않는 함수로, 어떠한 작업도 수행하지 않고 단순히 undefined을 반환합니다.

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

env 전용 함수​

createServerOnlyFn 및 createClientOnlyFn 헬퍼는 환경에 엄격히 한정된 실행을 강제합니다. 반환된 함수가 올바른 런타임 컨텍스트에서만 호출되도록 보장합니다. 잘못 사용하면 의도하지 않은 로직 실행을 방지하기 위해 설명이 포함된 런타임 오류를 발생시킵니다.

createServerOnlyFn​

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

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

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

createClientOnlyFn​

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

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

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

[!NOTE] 이러한 함수는 API 접근, 파일 시스템 읽기, 브라우저 API 사용 또는 의도된 환경 밖에서는 유효하지 않거나 안전하지 않은 기타 작업에 유용합니다.

트리 셰이킹​

환경 함수는 생성되는 각 번들의 환경에 따라 트리 셰이킹됩니다.

createIsomorphicFn()을 사용해 생성된 함수는 트리 셰이킹됩니다. .client() 내부의 모든 코드는 서버 번들에 포함되지 않으며, 그 반대도 마찬가지입니다.

서버에서는 createClientOnlyFn()을 사용해 생성된 함수가 서버에서 Error을 발생시키는 함수로 대체됩니다. 클라이언트의 createServerOnlyFn 함수에는 그 반대가 적용됩니다.