본문으로 건너뛰기
버전: 11.x

v10에서 v11로 마이그레이션

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

팁

대부분의 사용자에게 마이그레이션은 빠르고 직관적입니다.

아래 세 단계만으로 충분하지 않다면, 이어지는 문서에서 _"드물게 호환성 문제가 발생하는 변경 사항"_을 확인해 보세요.

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

자세한 내용은 트랜스포머가 링크로 이동됨를 참고하세요.

3. @trpc/react-query를 사용하는 경우 @tanstack/react-query 버전 업데이트​

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

전체 변경 사항​

새로운 TanStack React Query 통합! (비호환 변경 없음)​

tRPC v11에서 새로운 TanStack React Query 통합이 사용 가능하게 된 것을 기쁘게 발표합니다.

자세한 내용은 블로그 게시물를 읽어 보세요.

서버에서 구독 중지 (드물게 호환성 문제 발생)​

이제 서버에서 구독을 중지할 수 있으므로, 다음과 같은 작업을 수행할 수 있습니다:

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를 사용하여 HTTP/2 서버를 만들고 createHTTPServer를 사용하여 HTTP/1 서버를 만들 수 있습니다.

자세한 내용은 스탠드얼론 어댑터 문서를 참고하세요.

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

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

중첩 데이터에 Promise 임베딩 허용 (비호환 변경 없음)​

httpBatchStreamLink를 사용할 때 중첩 데이터에 Promise를 임베딩할 수 있으므로, 이제 다음과 같은 작업을 수행할 수 있습니다:

ts
const appRouter = t.router({
  embedPromise: publicProcedure.query(() => {
    async function slowThing() {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return 'slow';
    }
    return {
      instant: 'instant',
      slow: slowThing(),
    };
  }),
});
ts
const appRouter = t.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를 설치하려고 하면 설치 중에 피어 의존성 오류가 발생합니다.

편집기에서 any 타입이 표시되는 것을 확인했다면, 편집기가 올바른 TypeScript 버전을 사용하지 않고 있기 때문일 가능성이 높습니다. 이를 수정하려면 편집기를 프로젝트의 package.json에 설치된 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 이동 (비호환성 없음)​

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

오래된 연결을 감지하고 복구하는 기능에 대한 지원이 추가되었습니다:

서버에서 연결을 유지하기 위해 ping 간격을 구성할 수 있습니다:

ts
import { initTRPC } from '@trpc/server';
 
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
import { initTRPC } from '@trpc/server';
 
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 개선 (비호환성 없음)​

  • useSubscription 훅을 사용하여 프로시저에 구독할 때 이제 구독 및 연결의 상태에 대한 정보를 반환합니다.
  • httpSubscriptionLink에서 ponyfill을 지정할 수 있습니다.

구독 프로시저 출력 타입이 AsyncGenerator로 변경됨 (비호환성 없음)​

v11에서 비동기 제너레이터와 함께 구독을 사용했다면, 타입을 추론하는 방식에 따라 호환성 문제가 발생할 수 있습니다.

세부 정보

추론된 출력을 다음과 같이 변경했습니다:

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>;
}>;

값을 추론해야 하는 경우, 아래와 같은 헬퍼를 사용할 수 있습니다:

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 반환 구독의 비추천 (비호환성 없음)​

이제 구독에서 비동기 제너레이터 함수를 반환하는 것을 지원하며, 이전에 httpSubscriptionLink를 추가했습니다.

구독에 비동기 제너레이터 함수를 사용하는 방법을 보려면 구독 문서를 참조하세요.

AbortControllerEsque-ponyfill 제거 (드물게 호환성 문제 발생)​

tRPC에서 AbortControllerEsque ponyfill을 제거했습니다. 구형 브라우저를 지원해야 한다면 abortcontroller-polyfill 같은 polyfill을 사용할 수 있습니다.

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

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

👉 httpSubscriptionLink 문서에서 자세히 보기.

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

이제 httpBatchStreamLink를 사용하여 뮤테이션과 쿼리의 스트리밍을 지원합니다.

즉, 쿼리와 뮤테이션 리졸버는 yield를 사용하는 AsyncGenerator이거나 나중에 처리하도록 지연할 수 있는 Promise를 반환할 수 있습니다. 따라서 WebSocket 없이도 HTTP를 통해 응답을 스트리밍할 수 있습니다.

이 기능을 직접 사용해 보고 Discord의 🎏-rfc-streaming 채널에서 의견을 알려주세요!

👉 httpBatchStreamLink 문서에서 자세히 보기

resolveHTTPRequest가 Fetch API를 사용하는 resolveRequest로 대체됨 (드물게 호환성 문제 발생)​

resolveHTTPRequest 함수는 Fetch API의 Request와 Response를 사용하는 resolveRequest로 대체되었습니다.

이것은 HTTP 어댑터에 대한 호환성 변경 사항이지만, 사용자에게는 영향을 주지 않아야 합니다.

어댑터를 개발 중이라면 소스 코드에서 기존 어댑터의 동작 방식을 확인하세요. 도움이 필요하면 Discord에서 언제든 문의해 주세요.

TRPCRequestInfo 업데이트됨 (드물게 호환성 문제 발생)​

입력은 이제 프로시저가 필요로 할 때 지연 구체화되므로, tRPC가 createContext를 호출하는 시점에는 입력과 프로시저 타입을 더 이상 사용할 수 없습니다.

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

모든 실험적 form-data 지원이 대체됨 (드물게 호환성 문제 발생)​

실험적 form-data 기능을 사용한 경우에만 영향을 받습니다.

  • 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를 수동으로 호출할 때만 잠재적인 비호환 변경이 될 수 있습니다.

메서드 오버라이딩 지원 추가 (드물게 호환성 문제 발생)​

예를 들어 최대 URL 길이와 같은 제한 사항을 우회하기 위해 프로시저의 HTTP 메서드를 항상 POST로 전송하도록 오버라이드할 수 있습니다.

#3910 해결

양방향 무한 쿼리 지원 추가 (비호환 변경 없음)​

useInfiniteQuery() 참고

inferProcedureBuilderResolverOptions<T> 헬퍼 추가 (비호환 변경 없음)​

프로시저 빌더 리졸버의 옵션을 추론하는 헬퍼를 추가합니다. 이는 다른 프로시저를 위한 재사용 가능한 함수를 생성하려는 경우 유용합니다.

사용법에 대한 참고를 위해 여기의 테스트를 확인하세요

트랜스포머가 링크로 이동 (호환성 변경) -​

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
import { createTRPCNext } from '@trpc/next';
import superjson from 'superjson';
import { AppRouter } from './appRouter'
createTRPCNext<AppRouter>({
  // [..]
  transformer: superjson, // <-- add this
});
ts
import { createTRPCNext } from '@trpc/next';
import superjson from 'superjson';
import { AppRouter } from './appRouter'
createTRPCNext<AppRouter>({
  // [..]
  transformer: superjson, // <-- add this
});

@trpc/next SSR 모드에는 이제 ssr: true를 사용하는 prepass 헬퍼가 필요합니다 (드물게 호환성 문제 발생)​

이것은 이 기능을 사용하든 하지 않든 react-dom이 항상 가져와지던 https://github.com/trpc/trpc/issues/5378 문제를 수정하기 위한 것입니다.

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

내부 제네릭 리팩터링 (드물게 호환성 문제 발생)​

내부 제네릭을 리팩토링하여 가독성을 높였습니다.

React 18.2.0 이상 필요 (드물게 호환성 문제 발생)​

해당 마이그레이션 가이드를 확인하세요: https://react.dev/blog/2022/03/08/react-18-upgrade-guide

Node.js 18 이상 및 최신 브라우저 필요 (드물게 호환성 문제 발생)​

FormData, File, Blob, ReadableStream을 사용하게 되면서 Node.js 18 이상이 필요합니다. 브라우저에서는 이러한 기능을 이미 수년 전부터 지원해 왔습니다.

  • 배포 중 서버 위치가 변경될 경우 url 콜백에서 Promise를 전달할 수 있는 기능 추가
  • 대기 중인 요청이 없을 때 웹소켓이 자동으로 연결을 끊는 새로운 lazy 옵션 추가

미들웨어의 rawInput이 getRawInput으로 변경됨 (드물게 호환성 문제 발생)​

내부적으로 아직 다른 작업을 수행하지는 않지만(아직은), 이는 tRPC에서 오랫동안 요청되어 온 기능인 JSON 이외의 콘텐츠 타입 지원을 돕기 위한 것입니다.

타입 및 .d.ts 출력 단순화​

라우터의 프로시저는 이제 입력 및 출력만 출력합니다. 이전에는 모든 프로시저에 대해 전체 컨텍스트 객체를 포함하여 불필요한 복잡성을 유발했었으며, 예를 들어 .d.ts에서 그러했습니다.

React Query 피어 의존성이 v5로 변경됨 (비호환 변경) -​

수행해야 할 주요 작업은 isLoading을 isPending로 대체하는 것입니다

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

내보내기 이름 AbcProxyXyz가 AbcXyz로 변경됨 (비호환 변경 없음)​

프록시 이름은 v9에서 AbcXyz 이름을 사용했기 때문에 붙여진 것입니다. 이들은 제거되었고 프록시 이름은 비프록시 이름으로 변경되었습니다. 예:

  • createTRPCClient는 v9부터 비추천(deprecated)되었으며, 이제 완전히 제거되었습니다. createTRPCProxyClient는 대신 createTRPCClient로 이름이 변경되었습니다. createTRPCProxyClient는 이제 비추천(deprecated)으로 표시되었습니다.

SSG 헬퍼 (드물게 호환성 문제 발생)​

  • createSSGHelpers는 이제 제거된 v9용이었습니다. v10의 대응 항목인 createProxySSGHelpers는 이제 createSSGHelpers로 이름이 변경되었습니다.
  • createProxySSGHelpers는 이제 비추천(deprecated)되었지만, 하위 호환성을 위해 createSSGHelpers로 별칭이 지정되어 있습니다.
  • 내보내기된 타입 CreateSSGHelpersOptions 제거

interop 모드 제거 (드물게 호환성 문제 발생) -​

tRPC에서 interop-모드를 제거했습니다. 이 모드는 v9에서 v10으로의 쉬운 전환 기간을 제공하기 위한 것이었습니다. 이 모드는 장기적으로 지원될 목적으로 설계되지 않았으며, 이제 제거되었습니다.