본문으로 건너뛰기

서버 진입점

[!NOTE] 서버 진입점은 기본적으로 선택 사항입니다. 제공하지 않으면 TanStack Start가 아래 내용을 기본값으로 사용하여 서버 진입점을 자동으로 처리합니다.

서버 진입점은 Cloudflare Workers 및 기타 WinterCG 호환 런타임에서 일반적으로 사용하는 범용 fetch 핸들러 형식을 지원합니다.

상호 운용성을 보장하려면 기본 export가 ServerEntry 인터페이스를 준수해야 합니다:

export default {
  fetch(req: Request, opts?: RequestOptions): Response | Promise<Response> {
    // ...
  },
}

TanStack Start는 생성을 타입 안전하게 만드는 래퍼를 제공합니다. 이 작업은 src/server.ts 파일에서 수행됩니다.

// src/server.ts
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'

export default createServerEntry({
  fetch(request) {
    return handler.fetch(request)
  },
})

앱을 정적으로 생성하든 동적으로 제공하든, server.ts 파일은 모든 SSR 관련 작업을 수행하고 서버 라우트와 서버 함수 요청을 처리하는 진입점입니다.

사용자 지정 서버 핸들러​

애플리케이션의 렌더링 방식을 변경하는 사용자 지정 서버 핸들러를 만들 수 있습니다:

// src/server.ts
import {
  createStartHandler,
  defaultStreamHandler,
  defineHandlerCallback,
} from '@tanstack/react-start/server'
import { createServerEntry } from '@tanstack/react-start/server-entry'

const customHandler = defineHandlerCallback((ctx) => {
  // add custom logic here
  return defaultStreamHandler(ctx)
})

const fetch = createStartHandler(customHandler)

export default createServerEntry({
  fetch,
})

요청 컨텍스트​

서버에서 추가적인 타입 지정 데이터를 요청 핸들러에 전달해야 하는 경우(예: 인증된 사용자 정보, 데이터베이스 연결 또는 요청별 플래그), TypeScript 모듈 확장을 통해 요청 컨텍스트 타입을 등록합니다. 등록된 컨텍스트는 서버 fetch 핸들러의 두 번째 인수로 전달되며 전역 미들웨어, 요청/함수 미들웨어, 서버 라우트, 서버 함수 및 라우터 자체를 포함한 서버 측 미들웨어 체인 전체에서 사용할 수 있습니다.

요청 컨텍스트에 타입을 추가하려면 @tanstack/react-router의 Register 인터페이스를 server.requestContext 속성으로 확장합니다. 그러면 handler.fetch에 전달하는 런타임 context가 해당 타입과 일치하게 됩니다. 예:

import handler, { createServerEntry } from '@tanstack/react-start/server-entry'

type MyRequestContext = {
  hello: string
  foo: number
}

declare module '@tanstack/react-router' {
  interface Register {
    server: {
      requestContext: MyRequestContext
    }
  }
}

export default createServerEntry({
  async fetch(request) {
    return handler.fetch(request, { context: { hello: 'world', foo: 123 } })
  },
})

서버 구성​

서버 진입점에서 서버별 동작을 구성할 수 있습니다:

  • 요청/응답 미들웨어
  • 사용자 지정 오류 처리
  • 인증 로직
  • 데이터베이스 연결
  • 로깅 및 모니터링

이러한 유연성을 통해 프레임워크의 규칙을 유지하면서 TanStack Start 애플리케이션의 서버 측 렌더링 처리 방식을 사용자 지정할 수 있습니다.

Cloudflare Workers​

Cloudflare Workers에 배포할 때 server.ts를 확장하여 큐, 예약된 이벤트, Durable Objects와 같은 추가 Workers 기능을 처리할 수 있습니다. 종합적인 가이드는 TanStack Start용 Cloudflare Workers 문서를 참조하세요.