バージョン: 10.x

クイックスタート

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

tRPCはRESTとGraphQLの概念を組み合わせています。どちらにも慣れていない場合は、主要な概念を参照してください。

インストール

tRPCは複数のパッケージに分割されているため、必要なものだけをインストールできます。パッケージはコードベースの適切なセクションにインストールしてください。このクイックスタートガイドではシンプルに保つため、バニラクライアントのみを使用します。フレームワーク別ガイドについては、Reactでの使用方法とNext.jsでの使用方法を確認してください。

要件

tRPCにはTypeScript >= 4.7.0が必要です
公式に非strictモードをサポートしていないため、tsconfig.jsonで"strict": trueの使用を強く推奨します

まず、@trpc/serverと@trpc/clientパッケージをインストールします：

npm
yarn
pnpm
bun

sh
npm install @trpc/server @trpc/client

sh
npm install @trpc/server @trpc/client

sh
yarn add @trpc/server @trpc/client

sh
yarn add @trpc/server @trpc/client

sh
pnpm add @trpc/server @trpc/client

sh
pnpm add @trpc/server @trpc/client

sh
bun add @trpc/server @trpc/client

sh
bun add @trpc/server @trpc/client

バックエンドルーターの定義

tRPCで型安全なAPIを構築する手順を見ていきましょう。最初に、このAPIには以下のTypeScriptシグネチャを持つ3つのエンドポイントが含まれます：

ts
type User = { id: string; name: string; };
userList: () => User[];
userById: (id: string) => User;
userCreate: (data: { name: string }) => User;

ts
type User = { id: string; name: string; };
userList: () => User[];
userById: (id: string) => User;
userCreate: (data: { name: string }) => User;

1. ルーターインスタンスの作成

まずtRPCバックエンドを初期化します。tRPCオブジェクト全体ではなく、再利用可能なヘルパー関数をエクスポートするために、別ファイルで行うのが良い慣習です。

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
 
/**
 * Initialization of tRPC backend
 * Should be done only once per backend!
 */
const t = initTRPC.create();
 
/**
 * Export reusable router and procedure helpers
 * that can be used throughout the router
 */
export const router = t.router;
export const publicProcedure = t.procedure;

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
 
/**
 * Initialization of tRPC backend
 * Should be done only once per backend!
 */
const t = initTRPC.create();
 
/**
 * Export reusable router and procedure helpers
 * that can be used throughout the router
 */
export const router = t.router;
export const publicProcedure = t.procedure;

次にメインルーターインスタンス（通常appRouterと呼びます）を初期化し、後でプロシージャを追加します。最後に、クライアント側で後ほど使用するためにルーターの型をエクスポートする必要があります。

server/index.ts
ts
import { router } from './trpc';
 
const appRouter = router({
  // ...
});
 
// Export type router type signature,
// NOT the router itself.
export type AppRouter = typeof appRouter;

server/index.ts
ts
import { router } from './trpc';
 
const appRouter = router({
  // ...
});
 
// Export type router type signature,
// NOT the router itself.
export type AppRouter = typeof appRouter;

2. クエリプロシージャの追加

ルーターにクエリプロシージャを追加するにはpublicProcedure.query()を使用します。

以下はuserListというクエリプロシージャを作成し、データベースからユーザーリストを返します：

server/index.ts
ts
import { db } from './db';
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  userList: publicProcedure.query(async () => {
    // Retrieve users from a datasource, this is an imaginary database
    const users = await db.user.findMany();
           
const users: User[]
    return users;
  }),
});

server/index.ts
ts
import { db } from './db';
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  userList: publicProcedure.query(async () => {
    // Retrieve users from a datasource, this is an imaginary database
    const users = await db.user.findMany();
           
const users: User[]
    return users;
  }),
});

3. 入力パーサーを使用したプロシージャ入力の検証

userByIdプロシージャを実装するには、クライアントからの入力を受け入れる必要があります。tRPCでは入力パーサーを定義して入力を検証・解析できます。独自の入力パーサーを定義するか、zod、yup、superstructなどの検証ライブラリを使用できます。

入力パーサーはpublicProcedure.input()で定義し、下記のようにリゾルバー関数からアクセスできます：

Vanilla
Zod
Yup
Valibot

The input parser should be a function that validates and casts the input of this procedure. It should return a strongly typed value when the input is valid or throw an error if the input is invalid.

server/index.ts
ts
const appRouter = router({
  // ...
  userById: publicProcedure
    // The input is unknown at this time. A client could have sent
    // us anything so we won't assume a certain data type.
    .input((val: unknown) => {
      // If the value is of type string, return it.
      // It will now be inferred as a string.
      if (typeof val === 'string') return val;
 
      // Uh oh, looks like that input wasn't a string.
      // We will throw an error instead of running the procedure.
      throw new Error(`Invalid input: ${typeof val}`);
    })
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      // Retrieve the user with the given ID
      const user = await db.user.findById(input);
             
const user: User | undefined
      return user;
    }),
});

server/index.ts
ts
const appRouter = router({
  // ...
  userById: publicProcedure
    // The input is unknown at this time. A client could have sent
    // us anything so we won't assume a certain data type.
    .input((val: unknown) => {
      // If the value is of type string, return it.
      // It will now be inferred as a string.
      if (typeof val === 'string') return val;
 
      // Uh oh, looks like that input wasn't a string.
      // We will throw an error instead of running the procedure.
      throw new Error(`Invalid input: ${typeof val}`);
    })
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      // Retrieve the user with the given ID
      const user = await db.user.findById(input);
             
const user: User | undefined
      return user;
    }),
});

The input parser can be any ZodType, e.g. z.string() or z.object().

server.ts
ts
import { z } from 'zod';
import { db } from './db';
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  // ...
  userById: publicProcedure.input(z.string()).query(async (opts) => {
    const { input } = opts;
             
const input: string
    // Retrieve the user with the given ID
    const user = await db.user.findById(input);
           
const user: User | undefined
    return user;
  }),
});

server.ts
ts
import { z } from 'zod';
import { db } from './db';
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  // ...
  userById: publicProcedure.input(z.string()).query(async (opts) => {
    const { input } = opts;
             
const input: string
    // Retrieve the user with the given ID
    const user = await db.user.findById(input);
           
const user: User | undefined
    return user;
  }),
});

The input parser can be any YupSchema, e.g. yup.string() or yup.object().

server.ts
ts
import * as yup from 'yup';
import { db } from './db';
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  // ...
  userById: publicProcedure
    .input(yup.string().required())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      // Retrieve the user with the given ID
      const user = await db.user.findById(input);
             
const user: User | undefined
      return user;
    }),
});

server.ts
ts
import * as yup from 'yup';
import { db } from './db';
import { publicProcedure, router } from './trpc';
 
const appRouter = router({
  // ...
  userById: publicProcedure
    .input(yup.string().required())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      // Retrieve the user with the given ID
      const user = await db.user.findById(input);
             
const user: User | undefined
      return user;
    }),
});

With Valibot, you simply need to wrap your schema with TypeSchema.

server.ts
ts
// @filename: trpc.ts
// @include: trpc
// @filename: db.ts
// @include: db
// @filename: server.ts
// ---cut---
import { wrap } from '@decs/typeschema';
import { string } from 'valibot';
import { db } from './db';
import { publicProcedure, router } from './trpc';
const appRouter = router({
  // ...
  userById: publicProcedure.input(wrap(string())).query(async (opts) => {
    const { input } = opts;
    //      ^?
    // Retrieve the user with the given ID
    const user = await db.user.findById(input);
    //    ^?
    return user;
  }),
});

server.ts
ts
// @filename: trpc.ts
// @include: trpc
// @filename: db.ts
// @include: db
// @filename: server.ts
// ---cut---
import { wrap } from '@decs/typeschema';
import { string } from 'valibot';
import { db } from './db';
import { publicProcedure, router } from './trpc';
const appRouter = router({
  // ...
  userById: publicProcedure.input(wrap(string())).query(async (opts) => {
    const { input } = opts;
    //      ^?
    // Retrieve the user with the given ID
    const user = await db.user.findById(input);
    //    ^?
    return user;
  }),
});

情報

このドキュメントの残りの部分では、検証ライブラリとしてzodを使用します。

4. ミューテーションプロシージャの追加

GraphQLと同様に、tRPCはクエリプロシージャとミューテーションプロシージャを区別します。

サーバー上のプロシージャの動作は、クエリとミューテーションで大きな違いはありません。メソッド名が異なり、クライアントがこのプロシージャを使用する方法が変わるだけです。それ以外はすべて同じです！

ルーターオブジェクトに新しいプロパティとしてuserCreateミューテーションを追加しましょう：

server.ts
ts
const appRouter = router({
  // ...
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
               const input: {
    name: string;
}
      // Create a new user in the database
      const user = await db.user.create(input);
             const user: {
    name: string;
    id: string;
}
      return user;
    }),
});

server.ts
ts
const appRouter = router({
  // ...
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
               const input: {
    name: string;
}
      // Create a new user in the database
      const user = await db.user.create(input);
             const user: {
    name: string;
    id: string;
}
      return user;
    }),
});

APIの提供

ルーターを定義したので、提供できます。tRPCには多くのアダプターがあるため、任意のバックエンドフレームワークを使用できます。シンプルにするために、standaloneアダプターを使用します。

server/index.ts
ts
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { router } from './trpc';
 
const appRouter = router({
  // ...
});
 
const server = createHTTPServer({
  router: appRouter,
});
 
server.listen(3000);

server/index.ts
ts
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { router } from './trpc';
 
const appRouter = router({
  // ...
});
 
const server = createHTTPServer({
  router: appRouter,
});
 
server.listen(3000);

See the full backend code

server/db.ts
ts
type User = { id: string; name: string };
 
// Imaginary database
const users: User[] = [];
export const db = {
  user: {
    findMany: async () => users,
    findById: async (id: string) => users.find((user) => user.id === id),
    create: async (data: { name: string }) => {
      const user = { id: String(users.length + 1), ...data };
      users.push(user);
      return user;
    },
  },
};

server/db.ts
ts
type User = { id: string; name: string };
 
// Imaginary database
const users: User[] = [];
export const db = {
  user: {
    findMany: async () => users,
    findById: async (id: string) => users.find((user) => user.id === id),
    create: async (data: { name: string }) => {
      const user = { id: String(users.length + 1), ...data };
      users.push(user);
      return user;
    },
  },
};

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
 
const t = initTRPC.create();
 
export const router = t.router;
export const publicProcedure = t.procedure;

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
 
const t = initTRPC.create();
 
export const router = t.router;
export const publicProcedure = t.procedure;

server/index.ts
ts
import { createHTTPServer } from "@trpc/server/adapters/standalone";
import { z } from "zod";
import { db } from "./db";
import { publicProcedure, router } from "./trpc";
 
const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users = await db.user.findMany();
      return users;
    }),
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
      const user = await db.user.findById(input);
      return user;
    }),
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
      const user = await db.user.create(input);
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;
 
const server = createHTTPServer({
  router: appRouter,
});
 
server.listen(3000);

server/index.ts
ts
import { createHTTPServer } from "@trpc/server/adapters/standalone";
import { z } from "zod";
import { db } from "./db";
import { publicProcedure, router } from "./trpc";
 
const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users = await db.user.findMany();
      return users;
    }),
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
      const user = await db.user.findById(input);
      return user;
    }),
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
      const user = await db.user.create(input);
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;
 
const server = createHTTPServer({
  router: appRouter,
});
 
server.listen(3000);

クライアント側での新しいバックエンドの使用

クライアントサイドのコードに移り、エンドツーエンドのタイプセーフティの力を実感しましょう。クライアントで使用するためにAppRouter型をインポートするだけで、実装の詳細をクライアントに漏らすことなくシステム全体の完全なタイプセーフティを実現できます。

1. tRPCクライアントのセットアップ

client/index.ts
ts
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './server';
 
//     👆 **type-only** import
 
// Pass AppRouter as generic here. 👇 This lets the `trpc` object know
// what procedures are available on the server and their input/output types.
const trpc = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});

client/index.ts
ts
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './server';
 
//     👆 **type-only** import
 
// Pass AppRouter as generic here. 👇 This lets the `trpc` object know
// what procedures are available on the server and their input/output types.
const trpc = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});

tRPCのリンクはGraphQLのリンクと似ており、データがサーバーに送信される前にデータフローを制御できます。上記の例ではhttpBatchLinkを使用しており、複数の呼び出しを単一のHTTPリクエストに自動的にまとめます。リンクのより詳細な使い方については、リンクのドキュメントを参照してください。

2. クエリとミューテーションの実行

これでtrpcオブジェクトを通じてAPIプロシージャにアクセスできます。実際に試してみましょう！

client/index.ts
ts
// Inferred types
const user = await trpc.userById.query('1');
       const user: {
    name: string;
    id: string;
} | undefined
 
const createdUser = await trpc.userCreate.mutate({ name: 'sachinraja' });
          const createdUser: {
    name: string;
    id: string;
}

client/index.ts
ts
// Inferred types
const user = await trpc.userById.query('1');
       const user: {
    name: string;
    id: string;
} | undefined
 
const createdUser = await trpc.userCreate.mutate({ name: 'sachinraja' });
          const createdUser: {
    name: string;
    id: string;
}

完全なオートコンプリート

Intellisenseを開くと、フロントエンドでAPIを探索できます。すべてのプロシージャルートとそれらを呼び出すメソッドが用意されているのが確認できます。

client/index.ts
ts
// Full autocompletion on your routes
trpc.u;
      userById
userCreate
userList

client/index.ts
ts
// Full autocompletion on your routes
trpc.u;
      userById
userCreate
userList

実際に試してみましょう！

次のステップ

ヒント

お気に入りのフレームワークでtRPCをどのようにインストールするか学ぶには、サンプルアプリを確認することを強くお勧めします。

ヒント

デフォルトでは、tRPCはDateのような複雑な型をJSON互換の形式（Dateの場合はstring）にマッピングします。これらの型の整合性を保持したい場合は、superjsonを使用するのがデータトランスフォーマーとして最も簡単な方法です。

tRPCにはReactプロジェクトやNext.js向けに設計された、より高度なクライアントサイドツールが含まれています。

インストール​

バックエンドルーターの定義​

1. ルーターインスタンスの作成​

2. クエリプロシージャの追加​

3. 入力パーサーを使用したプロシージャ入力の検証​

4. ミューテーションプロシージャの追加​

APIの提供​

クライアント側での新しいバックエンドの使用​

1. tRPCクライアントのセットアップ​

2. クエリとミューテーションの実行​

完全なオートコンプリート​

実際に試してみましょう！​

次のステップ​