본문 바로가기
버전: 11.x

v10에서 v11로 마이그레이션

비공식 베타 번역

이 페이지는 PageTurner AI로 번역되었습니다(베타). 프로젝트 공식 승인을 받지 않았습니다. 오류를 발견하셨나요? 문제 신고 →

v10에서 v11로 마이그레이션​

팁

대부분의 사용자에게 마이그레이션은 빠르고 간단할 것입니다.

아래 세 단계로 충분하지 않다면, 문서에서 "거의 깨지지 않는 변경점(rarely breaking)" 을 찾아보세요.

1. 새 버전 설치​

npm install @trpc/server@^11 @trpc/client@^11 @trpc/react-query@^11 @trpc/next@^11 @tanstack/react-query@^5 @tanstack/react-query-devtools@^5

2. transformer를 사용 중이라면 링크 업데이트​

자세한 내용은 transformers가 links로 이동됨을 참조하세요.

3. @trpc/react-query를 사용 중이라면 @tanstack/react-query 버전 업데이트​

자세한 내용은 react-query-v5를 참조하세요.

전체 역순 변경 로그​

새로운 TanStack React Query 통합! (비호환)​

tRPC의 next 릴리스에서 새로운 TanStack React Query 통합을 사용할 수 있습니다!

Read the blog post for more information.

서버 측에서 구독 중지 기능 (거의 호환 안 깨짐)​

이제 서버 측에서 구독을 중지할 수 있습니다. 예를 들어 다음과 같은 작업이 가능해졌습니다:

ts
const myRouter = router({
  sub: publicProcedure.subscription(async function* (opts) {
    for await (const data of on(ee, 'data', {
      signal: opts.signal,
    })) {
      const num = data[0] as number | undefined;
      if (num === undefined) {
        // This will now stop the subscription on the client and trigger the `onComplete` callback
        return;
      }
      yield num;
    }
  }),
});
ts
const myRouter = router({
  sub: publicProcedure.subscription(async function* (opts) {
    for await (const data of on(ee, 'data', {
      signal: opts.signal,
    })) {
      const num = data[0] as number | undefined;
      if (num === undefined) {
        // This will now stop the subscription on the client and trigger the `onComplete` callback
        return;
      }
      yield num;
    }
  }),
});

자세한 내용은 구독 문서를 참조하세요.

지연 로딩 라우터 지원 추가 (비호환)​

자세한 내용은 지연 로딩 라우터 문서를 참조하세요.

이와 관련하여 내부 메서드 callProcedure()의 인수가 { _def: AnyRouter['_def'] } 대신 { router: AnyRouter } 파라미터를 받도록 변경되었습니다.

독립형 어댑터에서 요청 처리용 사용자 정의 basePath (비호환)​

독립형 어댑터에서 이제 basePath 옵션을 지원하며, 이 옵션은 요청 경로의 시작 부분에서 basePath를 잘라냅니다.

자세한 내용은 독립형 어댑터 문서를 참조하세요.

HTTP/2 서버 지원 추가 (비호환)​

이제 HTTP/2 서버를 지원하므로 createHTTP2Handler 및 createHTTPServer 함수를 사용해 HTTP/2 서버를 생성할 수 있습니다.

자세한 내용은 독립형 어댑터 문서를 참조하세요.

TRPCProcedureOptions를 @trpc/client로 이동 (대부분 비호환)​

이전에 @trpc/server에서 ProcedureOptions를 사용했다면, 이제 @trpc/client의 TRPCProcedureOptions를 사용해야 합니다.

중첩 데이터에 프로미스 임베딩 허용 (비호환)​

이제 httpBatchStreamLink 사용 시 중첩 데이터에 프로미스를 임베딩할 수 있게 되어 다음과 같은 작업이 가능해졌습니다:

ts
const router = router({
  embedPromise: publicProcedure.query(() => {
    async function slowThing() {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'slow';
    }
    return {
      instant: 'instant',
      slow: slowThing(),
    };
  }),
});
ts
const router = router({
  embedPromise: publicProcedure.query(() => {
    async function slowThing() {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'slow';
    }
    return {
      instant: 'instant',
      slow: slowThing(),
    };
  }),
});

reconnectAfterInactivityMs를 sse.client로 이동 (비호환)​

HTTP 구독 링크 개선 사항 섹션과 관련 문서를 업데이트했습니다.

TypeScript 버전 >=5.7.2 필수 요구 (비호환)​

tRPC는 이제 TypeScript 버전 5.7.2 이상을 요구합니다. 이 변경은 버그 리포트에 대한 대응으로 미래 지향적인 접근 방식을 채택하기 위해 이루어졌습니다.

지원되지 않는 TypeScript 버전으로 tRPC를 설치하려고 하면 설치 과정에서 peer dependency 오류가 발생합니다.

에디터에서 any 타입이 표시된다면, 프로젝트의 package.json에 설치된 TypeScript 버전을 사용하도록 에디터가 설정되지 않았기 때문일 수 있습니다. 이 문제를 해결하려면 에디터가 프로젝트의 TypeScript 버전을 사용하도록 설정해야 합니다.

VSCode 사용자는 .vscode/settings.json에 다음 설정을 추가하세요:

.vscode/settings.json
json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}
.vscode/settings.json
json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

experimental.sseSubscriptions를 sse로 이동 (비호환적 변경 없음)​

initTRPC.create() 함수에서 experimental.sseSubscriptions 옵션이 sse로 단순화되었습니다.

오래된 연결 감지 및 복구 기능 추가:

서버 측에서 연결 유지를 위한 ping 간격을 구성할 수 있습니다:

ts
export const t = initTRPC.create({
  // ...
  sse: {
    ping: {
      enabled: true,
      intervalMs: 15_000,
    },
    client: {
      // Reconnect if no messages or pings are received for 20 seconds
      reconnectAfterInactivityMs: 20_000,
    },
  },
});
ts
export const t = initTRPC.create({
  // ...
  sse: {
    ping: {
      enabled: true,
      intervalMs: 15_000,
    },
    client: {
      // Reconnect if no messages or pings are received for 20 seconds
      reconnectAfterInactivityMs: 20_000,
    },
  },
});

향후 기본 ping 간격과 타임아웃 설정을 추가할 예정이며, 아직 최종 결정되지 않았습니다. 피드백은 Discord의 🎏-rfc-streaming 채널로 부탁드립니다.

이 기능들에 대한 자세한 내용은 httpSubscriptionLink 문서를 참조하세요.

retryLink 참조 - 실패한 작업 재시도 가능

useSubscription 개선 (비호환적 변경 없음)​

구독 절차 출력 타입이 AsyncGenerator로 변경 (비호환적 변경 없음)​

v11에서 async generator를 사용한 구독을 구현했다면 타입 추론 방식이 변경되어 호환성 문제가 발생할 수 있습니다.

Details

We changed the inferred output from:

ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: __OUTPUT__;
}>;
ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: __OUTPUT__;
}>;

to

ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: AsyncGenerator<__OUTPUT__, void, unknown>;
}>;
ts
SubscriptionProcedure<{
  input: __INPUT__;
  output: AsyncGenerator<__OUTPUT__, void, unknown>;
}>;

If you need to infer the value you can use a helper like the below:

ts
type inferAsyncIterableYield<TOutput> =
  TOutput extends AsyncGenerator<infer $Yield> ? $Yield : never;
ts
type inferAsyncIterableYield<TOutput> =
  TOutput extends AsyncGenerator<infer $Yield> ? $Yield : never;

이 변경은 라이브러리가 향후 업데이트와 호환성을 유지하고 구독의 AsyncGenerator에서 return 타입 사용을 가능하게 하기 위해 적용되었습니다.

자세한 내용은 구독 문서를 참조하세요.

구독에서 출력 유효성 검사기 지원 추가 (비호환적 변경 없음)​

자세한 내용은 구독 문서를 참조하세요.

Observable 반환 구독 방식 지원 중단 (비호환적 변경 없음)​

이제 구독을 위해 async generator 함수 반환을 지원하며, 이전에 httpSubscriptionLink를 추가했습니다.

구독에 async generator 함수 사용 방법은 구독 문서를 참조하세요.

AbortControllerEsque 폴리필 제거 (드물게 호환성 깨짐)​

tRPC에서 AbortControllerEsque 폴리필을 제거했습니다. 구형 브라우저 지원이 필요한 경우 abortcontroller-polyfill 같은 폴리필을 사용할 수 있습니다.

서버 전송 이벤트(SSE) 지원 (비호환적 변경 없음)​

이제 구독을 위한 SSE를 지원하므로, 애플리케이션에서 실시간 업데이트를 받기 위해 WebSocket 서버를 구동할 필요가 없으며 연결이 끊어졌을 때 클라이언트가 자동으로 재연결하고 재개할 수 있습니다.

👉 자세한 내용은 httpSubscriptionLink 문서 참조.

HTTP를 통한 스트리밍 응답 지원 (비호환적 변경 없음)​

이제 httpBatchStreamLink를 사용해 변이(mutation) 및 쿼리의 스트리밍이 가능합니다.

이는 쿼리 및 뮤테이션 리졸버가 AsyncGenerator와 yield를 사용하거나 지연될 수 있는 프라미스를 반환할 수 있음을 의미합니다. 따라서 WebSocket 없이도 HTTP를 통해 스트림 응답을 사용할 수 있습니다.

이 기능에 대한 피드백을 환영합니다! 사용해 보신 후 저희 디스코드의 🎏-rfc-streaming 채널에서 의견을 공유해 주세요.

👉 httpBatchStreamLink 문서에서 자세히 보기

resolveHTTPRequest이 Fetch API를 사용하는 resolveRequest로 대체됨 (드물게 호환성 깨짐)​

resolveHTTPRequest 함수가 Fetch API(Request/Response)를 사용하는 resolveRequest로 대체되었습니다.

이는 HTTP 어댑터에 대한 호환성 변경 사항이지만, 일반 사용자에게는 영향을 미치지 않습니다.

어댑터를 개발 중이라면 코드에서 어댑터 작동 방식을 참고하고 디스코드에서 도움을 요청하세요.

TRPCRequestInfo 업데이트 (드물게 호환성 깨짐)​

이제 입력은 프로시저에서 필요할 때 지연 평가(lazy evaluation)되므로, createContext 호출 시점에는 입력 데이터와 프로시저 타입을 사용할 수 없습니다.

대신 info.calls[index].getRawInput()을 호출하여 원시 입력에 접근할 수 있습니다.

실험적 Form-Data 지원 전면 교체 (드물게 호환성 깨짐)​

실험적 FormData 기능을 사용한 경우에만 영향을 미침

  • experimental_formDataLink → httpLink 사용

  • experimental_parseMultipartFormData → 더 이상 필요 없음

  • experimental_isMultipartFormDataRequest → 더 이상 필요 없음

  • experimental_composeUploadHandlers → 더 이상 필요 없음

  • experimental_createMemoryUploadHandler → 더 이상 필요 없음

  • experimental_NodeOnDiskFile 및 experimental_createFileUploadHandler → 이번 릴리스에서 지원 중단. 디스크 데이터 저장이 필요하면 이슈 등록

  • experimental_contentTypeHandlers → 더 이상 필요 없음. 커뮤니티 요청 시 새로운 데이터 타입 지원으로 복귀 가능

새로운 접근 방식은 examples/next-formdata에서 확인 가능

Procedure._def._output_in / Procedure._def._input_in을 Procedure._def.$types로 이동 (호환성 유지)​

tRPC 내부 호환성이 깨지는 변경이지만 일반 사용자에게는 영향 없음

Procedure._def._output_in 또는 Procedure._def._input_in을 직접 사용하지 않는 한 조치 불필요

명시적 Content-Type 검사 추가 (호환성 유지)​

POST 요청 시 Content-Type 헤더에 대한 명시적 검사가 추가되었습니다. 예상과 다른 Content-Type으로 요청을 보낼 경우 415 Unsupported Media Type 오류가 발생합니다.

tRPC 클라이언트는 자동으로 content-type 헤더를 전송하므로, tRPC를 수동으로 호출하는 경우에만 영향이 있을 수 있습니다.

메서드 오버라이딩 지원 추가 (드물게 호환성 깨짐)​

프로시저의 HTTP 메서드를 항상 POST로 강제 변경할 수 있게 되어 URL 최대 길이 제한 같은 문제를 우회할 수 있습니다.

#3910 이슈 해결

양방향 무한 쿼리 지원 추가 (호환성 유지)​

useInfiniteQuery() 참조

inferProcedureBuilderResolverOptions<T> 헬퍼 추가 (호환성 유지)​

프로시저 빌더 리졸버 옵션을 추론하는 헬퍼를 추가합니다. 다양한 프로시저에 재사용 가능한 함수를 생성할 때 유용합니다.

사용법 참조를 위해 테스트 코드 확인

변환기(transformers)를 링크로 이동 (호환성 변경) -​

TypeScript가 이 마이그레이션을 안내합니다

데이터 변환기 사용자만 해당

이제 데이터 변환기는 tRPC 클라이언트 초기화 시점이 아닌 links 배열에서 설정합니다:

변환기를 사용하는 경우 모든 HTTP 링크에 transformer: superjson를 추가해야 합니다:

ts
httpBatchLink({
  url: '/api/trpc',
  transformer: superjson, // <-- add this
});
ts
httpBatchLink({
  url: '/api/trpc',
  transformer: superjson, // <-- add this
});
ts
createTRPCNext<AppRouter>({
  // [..]
  transformer: superjson, // <-- add this
});
ts
createTRPCNext<AppRouter>({
  // [..]
  transformer: superjson, // <-- add this
});

@trpc/next SSR 모드에서 이제 ssr: true와 사전 패스(prepass) 헬퍼 필요 (드물게 호환성 변경)​

https://github.com/trpc/trpc/issues/5378 이슈 해결을 위한 변경으로, 해당 기능 사용 여부와 관계없이 react-dom이 항상 임포트되는 문제를 수정했습니다.

SSR 문서 참조

단축 라우터 정의 지원 추가 (호환성 유지)​

라우터 병합 문서 참조

ts
const appRouter = router({
  // Shorthand plain object for creating a sub-router
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // Equivalent of:
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});
ts
const appRouter = router({
  // Shorthand plain object for creating a sub-router
  nested1: {
    proc: publicProcedure.query(() => '...'),
  },
  // Equivalent of:
  nested2: router({
    proc: publicProcedure.query(() => '...'),
  }),
});

inferHandlerInput<T> 및 ProcedureArgs<T> 삭제 (대부분 호환성 유지)​

해당 타입을 사용하지 않거나 익숙하지 않다면 무시해도 좋습니다

대신 inferProcedureInput<TProcedure>와 TRPCProcedureOptions를 사용하세요

useSuspenseQueries() 추가​

useSuspenseQueries 참조

https://github.com/trpc/trpc/pull/5226

내부 제네릭 리팩토링 (드물게 호환성 변경)​

내부 제네릭을 리팩토링하여 가독성을 개선했습니다 (TODO: 프로시저 빌더 구현 링크 추가)

React 최소 버전 18.2.0으로 업그레이드 (드물게 호환성 변경)​

공식 마이그레이션 가이드 참조: https://react.dev/blog/2022/03/08/react-18-upgrade-guide

NodeJS 18+ 및 최신 브라우저 필수 요구사항 (드물게 호환성 변경)​

FormData, File, Blob, ReadableStream 사용이 추가되었습니다. 브라우저에서는 오래전부터 지원되었으나 NodeJS 18이 필수 요구사항이 되었습니다.

  • 배포 중 서버 위치 변경 시 url 콜백에서 Promise 전달 가능

  • 대기 중인 요청이 없을 때 웹소켓이 자동으로 연결 해제되는 새로운 lazy 옵션 추가

미들웨어에서 rawInput이 getRawInput으로 변경 (드물게 호환성 변경)​

내부 동작은 아직 변경되지 않았으나(현재 시점), tRPC에서 많이 요청되던 기능인 JSON 외 콘텐츠 타입 지원을 위한 기반 작업입니다.

타입 및 .d.ts 출력 간소화​

이제 라우터의 프로시저들은 입력(input)과 출력(output)만 노출합니다. 이전에는 모든 프로시저에 전체 컨텍스트 객체가 포함되어 .d.ts 등에서 불필요한 복잡성을 야기했습니다.

React Query peerDep 버전 v5로 변경 (호환성 변경) -​

주로 해야 할 작업은 여러 isLoading을 isPending으로 바꾸는 것입니다.

해당 마이그레이션 가이드를 확인하세요: https://tanstack.com/query/v5/docs/framework/react/guides/migrating-to-v5

내보내기 이름 AbcProxyXyz가 AbcXyz로 변경됨 (호환성 유지됨)​

프록시 이름은 v9에서 AbcXyz 이름을 사용했기 때문에 존재했으며, 이제 해당 이름들은 제거되고 프록시 이름들이 비프록시 이름으로 변경되었습니다. 예시:

  • createTRPCClient는 v9에서 사용 중단되었으며 현재 완전히 제거되었습니다. createTRPCProxyClient는 createTRPCClient로 이름이 변경되었습니다. createTRPCProxyClient는 현재 사용 중단 상태입니다.

SSG 헬퍼 (거의 호환성 깨짐 없음)​

  • createSSGHelpers는 v9용으로 제공되었으며 현재 제거되었습니다. v10의 해당 기능인 createProxySSGHelpers는 이제 createSSGHelpers로 이름이 변경되었습니다.

  • createProxySSGHelpers는 현재 사용 중단되었지만 하위 호환성을 위해 createSSGHelpers로 별칭 처리되어 있습니다.

  • 내보낸 타입 CreateSSGHelpersOptions가 제거됨

interop 모드 제거됨 (거의 호환성 깨짐 없음) -​

tRPC에서 interop 모드를 제거했습니다. 이 모드는 v9에서 v10으로의 쉬운 전환을 위해 제공되었으며, 장기 지원을 의도하지 않았습니다.