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

Standalone 어댑터

비공식 베타 번역

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

tRPC의 Standalone 어댑터는 새 프로젝트를 시작하는 가장 간단한 방법입니다. 로컬 개발 및 서버 기반 프로덕션 환경에 이상적입니다. 본질적으로 tRPC 관련 일반 옵션이 추가된 표준 Node.js HTTP 서버의 래퍼입니다.

기존에 Express, Fastify, Next.js 같은 API 배포 환경이 있고 여기에 tRPC를 통합하려는 경우, 해당 어댑터를 살펴보세요. 마찬가지로 서버리스나 에지 컴퓨팅 호스팅을 선호한다면 AWS Lambda나 Fetch 같은 요구에 맞는 어댑터를 사용할 수 있습니다.

배포용 어댑터가 로컬 머신에서 실행하기 어려운 경우, 애플리케이션에 2개의 진입점(entry-point)을 두는 것도 흔한 방법입니다. 로컬 개발에는 Standalone 어댑터를 사용하고 배포 시에는 다른 어댑터를 사용할 수 있습니다.

예시 애플리케이션​

DescriptionLinks
Standalone tRPC Server
Standalone tRPC Server with CORS handling

Standalone tRPC 서버 설정하기​

1. 앱 라우터 구현하기​

tRPC 라우터를 구현하세요. 예시:

appRouter.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
export const t = initTRPC.create();
export const appRouter = t.router({
  getUser: t.procedure.input(z.string()).query((opts) => {
    return { id: opts.input, name: 'Bilbo' };
  }),
  createUser: t.procedure
    .input(z.object({ name: z.string().min(5) }))
    .mutation(async (opts) => {
      // use your ORM of choice
      return await UserModel.create({
        data: opts.input,
      });
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;
appRouter.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
export const t = initTRPC.create();
export const appRouter = t.router({
  getUser: t.procedure.input(z.string()).query((opts) => {
    return { id: opts.input, name: 'Bilbo' };
  }),
  createUser: t.procedure
    .input(z.object({ name: z.string().min(5) }))
    .mutation(async (opts) => {
      // use your ORM of choice
      return await UserModel.create({
        data: opts.input,
      });
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

자세한 내용은 빠른 시작 가이드를 참조하세요.

2. Standalone 어댑터 사용하기​

Standalone 어댑터는 간단한 Node.js HTTP 서버를 실행합니다.

server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter.ts';
createHTTPServer({
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
}).listen(2022);
server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter.ts';
createHTTPServer({
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
}).listen(2022);

CORS 및 OPTIONS 처리하기​

기본적으로 standalone 서버는 HTTP OPTIONS 요청에 응답하거나 CORS 헤더를 설정하지 않습니다.

로컬 개발 중처럼 이를 처리해주는 환경에서 호스팅하지 않는 경우, 직접 처리해야 할 수 있습니다.

1. cors 설치하기​

인기 있는 cors 패키지로 직접 지원 기능을 추가할 수 있습니다

bash
yarn add cors
yarn add -D @types/cors
bash
yarn add cors
yarn add -D @types/cors

이 패키지 구성 방법에 대한 전체 정보는 공식 문서를 참조하세요.

2. Standalone 서버 구성하기​

이 예시는 개발에 유용한 모든 요청에 대해 CORS를 완전히 개방하지만, 프로덕션 환경에서는 더 엄격하게 구성해야 합니다.

server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import cors from 'cors';
createHTTPServer({
  middleware: cors(),
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
}).listen(3333);
server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import cors from 'cors';
createHTTPServer({
  middleware: cors(),
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
}).listen(3333);

middleware 옵션은 connect/node.js 미들웨어와 유사한 모든 함수를 수락하므로 원한다면 cors 처리 외에도 다양한 용도로 사용할 수 있습니다. 다만 이는 단순한 탈출구(escape hatch)로 설계되었으며, 그 자체로 여러 미들웨어를 함께 구성할 수는 없습니다. 이를 원한다면 다음 방법을 고려하세요:

  1. Express 어댑터처럼 더 포괄적인 미들웨어 지원을 제공하는 대체 어댑터 사용하기

  2. connect 같은 미들웨어 구성 솔루션 사용하기

  3. 커스텀 HTTP 서버로 Standalone createHTTPHandler 확장하기 (아래 참조)

더 나아가기​

createHTTPServer로 충분하지 않은 경우, standalone 어댑터의 createHTTPHandler 함수를 사용하여 자체 HTTP 서버를 생성할 수도 있습니다. 예를 들어:

server.ts
ts
import { createServer } from 'http';
import { initTRPC } from '@trpc/server';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
const handler = createHTTPHandler({
  router: appRouter,
  createContext() {
    return {};
  },
});
createServer((req, res) => {
  /**
   * Handle the request however you like,
   * just call the tRPC handler when you're ready
   */
  handler(req, res);
}).listen(3333);
server.ts
ts
import { createServer } from 'http';
import { initTRPC } from '@trpc/server';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
const handler = createHTTPHandler({
  router: appRouter,
  createContext() {
    return {};
  },
});
createServer((req, res) => {
  /**
   * Handle the request however you like,
   * just call the tRPC handler when you're ready
   */
  handler(req, res);
}).listen(3333);