Snabbstart

Inofficiell Beta-översättning

Denna sida har översatts av PageTurner AI (beta). Inte officiellt godkänd av projektet. Hittade du ett fel? Rapportera problem →

Installation

tRPC är uppdelat i flera paket så du kan installera precis det du behöver. Se till att installera paketen i rätt delar av din kodbas. I denna snabbstart håller vi det enkelt och använder endast vanilla-klienten. För ramverksspecifika guider, kolla in användning med React och användning med Next.js.

Krav

• tRPC kräver TypeScript >=5.7.2
• Vi rekommenderar starkt att använda "strict": true i din tsconfig.json då vi inte officiellt stöder icke-strikt läge.

Börja med att installera paketen @trpc/server och @trpc/client:

npm

npm install @trpc/server @trpc/client

yarn

yarn add @trpc/server @trpc/client

pnpm

pnpm add @trpc/server @trpc/client

bun

bun add @trpc/server @trpc/client

deno

deno add npm:@trpc/server npm:@trpc/client

AI-agenter

Om du använder en AI-kodningsagent, installera tRPC-färdigheter för bättre kodgenerering:

bash
npx @tanstack/intent@latest install

bash
npx @tanstack/intent@latest install

Ditt första tRPC-API

Låt oss gå igenom stegen för att bygga ett typesäkert API med tRPC. Till att börja med kommer detta API innehålla tre endpoints med följande TypeScript-signaturer:

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;

Här är filstrukturen vi kommer bygga. Vi rekommenderar att separera tRPC-initiering, routerdefinition och serverkonfiguration i distinkta filer för att undvika cirkulära beroenden:

.
├── server/
│   ├── trpc.ts        # tRPC instantiation & setup
│   ├── appRouter.ts   # Your API logic and type export
│   └── index.ts       # HTTP server
└── client/
    └── index.ts       # tRPC client

.
├── server/
│   ├── trpc.ts        # tRPC instantiation & setup
│   ├── appRouter.ts   # Your API logic and type export
│   └── index.ts       # HTTP server
└── client/
    └── index.ts       # tRPC client

1. Skapa en router-instans

Först initialiserar vi tRPC-backenden. Det är god praxis att göra detta i en separat fil och exportera återanvändbara hjälpfunktioner istället för hela tRPC-objektet.

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;

Därefter initierar vi vår huvudrouter-instans, vanligtvis kallad appRouter, som vi senare kommer lägga till procedurer på. Slutligen behöver vi exportera routertypen som vi ska använda på klientsidan.

server/appRouter.ts
ts
import { router } from './trpc';
 
export const appRouter = router({
  // ...
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { router } from './trpc';
 
export const appRouter = router({
  // ...
});
 
export type AppRouter = typeof appRouter;

2. Lägg till en query-procedure

Använd publicProcedure.query() för att lägga till en query-procedure till routern.

Följande skapar en query-procedure kallad userList som returnerar en lista med användare:

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
 
export const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users: User[] = [{ id: '1', name: 'Katt' }];
 
      return users;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
 
export const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users: User[] = [{ id: '1', name: 'Katt' }];
 
      return users;
    }),
});
 
export type AppRouter = typeof appRouter;

3. Använda input-parser för att validera procedure-input

För att implementera userById-proceduren behöver vi acceptera input från klienten. tRPC låter dig definiera input-parsers för att validera och tolka inputen. Du kan definiera din egen input-parser eller använda ett valfri valideringsbibliotek som zod, yup eller superstruct.

Du definierar din input-parser på publicProcedure.input(), som sedan kan nås i resolver-funktionen som visas nedan:

Vanilla

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.

information

Throughout the remainder of this documentation, we will use zod as our validation library.

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
 
export 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
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
 
export 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
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

Zod

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

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
import { z } from 'zod';
 
export const appRouter = router({
  // ...
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
import { z } from 'zod';
 
export const appRouter = router({
  // ...
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

Yup

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

information

Throughout the remainder of this documentation, we will use zod as our validation library.

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
import * as yup from 'yup';
 
export const appRouter = router({
  // ...
  userById: publicProcedure
    .input(yup.string().required())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
import * as yup from 'yup';
 
export const appRouter = router({
  // ...
  userById: publicProcedure
    .input(yup.string().required())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

Valibot

The input parser can be any Valibot schema, e.g. v.string() or v.object().

information

Throughout the remainder of this documentation, we will use zod as our validation library.

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
import * as v from 'valibot';
 
export const appRouter = router({
  // ...
  userById: publicProcedure
    .input(v.string())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
import * as v from 'valibot';
 
export const appRouter = router({
  // ...
  userById: publicProcedure
    .input(v.string())
    .query(async (opts) => {
      const { input } = opts;
               
const input: string
      const user: User = { id: input, name: 'Katt' };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

4. Lägga till en mutation-procedure

Liknande GraphQL gör tRPC en distinktion mellan Query- och Mutation-procedurer.

Skillnaden mellan Query och Mutation är främst semantisk. Queries använder HTTP GET och är avsedda för läsoperationer, medan Mutations använder HTTP POST och är avsedda för operationer som orsakar sidoeffekter.

Låt oss lägga till en userCreate-mutation genom att lägga till den som en ny egenskap på vårt router-objekt:

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
 
export const appRouter = router({
  // ...
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
               
const input: {
    name: string;
}
      // Create the user in your DB
      const user: User = { id: '1', ...input };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { publicProcedure, router } from './trpc';
 
export const appRouter = router({
  // ...
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
               
const input: {
    name: string;
}
      // Create the user in your DB
      const user: User = { id: '1', ...input };
 
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

Serva API:et

Nu när vi har definierat vår router kan vi serva den. tRPC har förstaklass adaptrar för många populära webbservrar. För att hålla det enkelt använder vi standalone-adaptern för Node.js här.

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

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

See the full backend code

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/appRouter.ts
ts
import { z } from "zod";
import { publicProcedure, router } from "./trpc";
 
type User = { id: string; name: string };
 
export const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users: User[] = [{ id: '1', name: 'Katt' }];
      return users;
    }),
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
      const user: User = { id: input, name: 'Katt' };
      return user;
    }),
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
      const user: User = { id: '1', ...input };
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

server/appRouter.ts
ts
import { z } from "zod";
import { publicProcedure, router } from "./trpc";
 
type User = { id: string; name: string };
 
export const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users: User[] = [{ id: '1', name: 'Katt' }];
      return users;
    }),
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
      const user: User = { id: input, name: 'Katt' };
      return user;
    }),
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
      const user: User = { id: '1', ...input };
      return user;
    }),
});
 
export type AppRouter = typeof appRouter;

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

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

Använda din nya backend på klienten

Låt oss nu gå vidare till klientsidan och ta tillvara kraften i end-to-end typesafety. När vi importerar AppRouter-typen för klienten att använda har vi uppnått fullständig typesafety i vårt system utan att läcka några implementeringsdetaljer till klienten.

1. Konfigurera tRPC-klienten

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

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

Länkar i tRPC liknar länkar i GraphQL – de låter oss kontrollera dataflödet till servern. I exemplet ovan använder vi httpBatchLink som automatiskt samlar flera anrop till en enda HTTP-förfrågan. För mer djupgående användning av länkar, se länkdokumentationen.

2. Typhinferens & Autocomplete

Du har nu tillgång till dina API-procedurer via trpc-objektet. Prova det!

client/index.ts
ts
// Inferred types
const user = await trpc.userById.query('1');
       
const user: User
 
const createdUser = await trpc.userCreate.mutate({ name: 'Katt' });
          
const createdUser: User

client/index.ts
ts
// Inferred types
const user = await trpc.userById.query('1');
       
const user: User
 
const createdUser = await trpc.userCreate.mutate({ name: 'Katt' });
          
const createdUser: User

Du kan också använda din autocomplete för att utforska API:et på din klient

client/index.ts
ts
trpc.u;
      
userById
userCreate
userList
 
 

client/index.ts
ts
trpc.u;
      
userById
userCreate
userList
 
 

Nästa steg

What's next?	Description
Example Apps	Explore tRPC in your chosen framework
TanStack React Query	Recommended React integration via @trpc/tanstack-react-query
Next.js	Usage with Next.js
Server Adapters	Express, Fastify, and more
Transformers	Use superjson to retain complex types like Date