Version: 11.x

Konfigurera med Next.js Pages Router

Inofficiell Beta-översättning

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

försiktighet

Denna guide gäller Next.js Pages Router. Om du använder Next.js App Router med React Server Components, kolla in RSC-dokumentationen

Rekommenderad filstruktur

Vi rekommenderar en filstruktur som denna, även om den inte är påbjuden av tRPC. Detta är vad du kommer se i våra exempel. Resten av denna sida guidar dig genom processen att integrera tRPC i denna struktur.

graphql
.
├── prisma  # <-- if prisma is added
│   └── [..]
├── src
│   ├── pages
│   │   ├── _app.tsx  # <-- add `withTRPC()`-HOC here
│   │   ├── api
│   │   │   └── trpc
│   │   │       └── [trpc].ts  # <-- tRPC HTTP handler
│   │   └── [..]
│   ├── server
│   │   ├── routers
│   │   │   ├── _app.ts  # <-- main app router
│   │   │   ├── post.ts  # <-- sub routers
│   │   │   └── [..]
│   │   ├── context.ts   # <-- create app context
│   │   └── trpc.ts      # <-- procedure helpers
│   └── utils
│       └── trpc.ts  # <-- your typesafe tRPC hooks
└── [..]

graphql
.
├── prisma  # <-- if prisma is added
│   └── [..]
├── src
│   ├── pages
│   │   ├── _app.tsx  # <-- add `withTRPC()`-HOC here
│   │   ├── api
│   │   │   └── trpc
│   │   │       └── [trpc].ts  # <-- tRPC HTTP handler
│   │   └── [..]
│   ├── server
│   │   ├── routers
│   │   │   ├── _app.ts  # <-- main app router
│   │   │   ├── post.ts  # <-- sub routers
│   │   │   └── [..]
│   │   ├── context.ts   # <-- create app context
│   │   └── trpc.ts      # <-- procedure helpers
│   └── utils
│       └── trpc.ts  # <-- your typesafe tRPC hooks
└── [..]

Lägg till tRPC i befintligt Next.js-projekt

1. Installera beroenden

npm
yarn
pnpm
bun
deno

npm install @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

yarn add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

pnpm add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

bun add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

deno add npm:@trpc/server npm:@trpc/client npm:@trpc/react-query npm:@trpc/next npm:@tanstack/react-query@latest npm:zod

Next.js-integrationen är en kombination av vår React Query Integration och några Next.js-specifika integrationer.

2. Aktivera strikt läge

Om du vill använda Zod för validering av indata, se till att du har aktiverat strikt läge i din tsconfig.json:

tsconfig.json
diff
"compilerOptions": {
+   "strict": true
}

tsconfig.json
diff
"compilerOptions": {
+   "strict": true
}

Om strikt läge är för restriktivt bör du åtminstone aktivera strictNullChecks:

tsconfig.json
diff
"compilerOptions": {
+   "strictNullChecks": true
}

tsconfig.json
diff
"compilerOptions": {
+   "strictNullChecks": true
}

3. Skapa en tRPC-router

Initiera din tRPC-backend i src/server/trpc.ts med funktionen initTRPC och skapa din första router. Här skapar vi en enkel "hello world"-router och procedur - för djupgående information om att skapa ditt tRPC-API bör du konsultera:

Snabbstartsguiden och Backend-dokumentationen för tRPC-information
Next.js Adapter-dokumentationen för att montera tRPC i din Next.js-server.

View sample backend

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;

server/routers/_app.ts
ts
import { z } from 'zod';
import { procedure, router } from '../trpc';
export const appRouter = router({
  hello: procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input.text}`,
      };
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

server/routers/_app.ts
ts
import { z } from 'zod';
import { procedure, router } from '../trpc';
export const appRouter = router({
  hello: procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input.text}`,
      };
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

pages/api/trpc/[trpc].ts
ts
import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
// export API handler
// @link https://trpc.io/docs/v11/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

pages/api/trpc/[trpc].ts
ts
import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
// export API handler
// @link https://trpc.io/docs/v11/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

notering

Backenden ovan använder den rekommenderade filstrukturen, men du kan hålla det enkelt och lägga allt direkt i en API-hanterare om du föredrar det.

4. Skapa tRPC-hooks

Använd funktionen createTRPCNext för att skapa en uppsättning starkt typade hooks från din API:typ-signatur.

utils/trpc.ts
tsx
import { httpBatchLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
function getBaseUrl() {
  if (typeof window !== 'undefined')
    // browser should use relative path
    return '';
  if (process.env.VERCEL_URL)
    // reference for vercel.com
    return `https://${process.env.VERCEL_URL}`;
  if (process.env.RENDER_INTERNAL_HOSTNAME)
    // reference for render.com
    return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`;
  // assume localhost
  return `http://localhost:${process.env.PORT ?? 3000}`;
}
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        httpBatchLink({
          /**
           * If you want to use SSR, you need to use the server's full URL
           * @see https://trpc.io/docs/v11/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/v11/ssr
   **/
  ssr: false,
});

utils/trpc.ts
tsx
import { httpBatchLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
function getBaseUrl() {
  if (typeof window !== 'undefined')
    // browser should use relative path
    return '';
  if (process.env.VERCEL_URL)
    // reference for vercel.com
    return `https://${process.env.VERCEL_URL}`;
  if (process.env.RENDER_INTERNAL_HOSTNAME)
    // reference for render.com
    return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`;
  // assume localhost
  return `http://localhost:${process.env.PORT ?? 3000}`;
}
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        httpBatchLink({
          /**
           * If you want to use SSR, you need to use the server's full URL
           * @see https://trpc.io/docs/v11/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/v11/ssr
   **/
  ssr: false,
});

notering

createTRPCNext fungerar inte med tRPC-v9:s interoperabilitetsläge. Om du migrerar från v9 med interoperabilitetsläget bör du fortsätta använda det gamla sättet att initiera tRPC.

5. Konfigurera `_app.tsx`

Omsluts din rotapp-sida i trpc.withTRPC HOC, ungefär så här:

pages/_app.tsx
tsx
import type { AppType } from 'next/app';
import { trpc } from '../utils/trpc';
const MyApp: AppType = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};
export default trpc.withTRPC(MyApp);

pages/_app.tsx
tsx
import type { AppType } from 'next/app';
import { trpc } from '../utils/trpc';
const MyApp: AppType = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};
export default trpc.withTRPC(MyApp);

6. Gör en API-förfrågan

Klart!

Du kan nu använda React-hooksen du precis skapat för att anropa ditt API. För mer detaljer, se React Query Integration

pages/index.tsx
tsx
import { trpc } from '../utils/trpc';
export default function IndexPage() {
  const hello = trpc.hello.useQuery({ text: 'client' });
  if (!hello.data) {
    return <div>Loading...</div>;
  }
  return (
    <div>
      <p>{hello.data.greeting}</p>
    </div>
  );
}

pages/index.tsx
tsx
import { trpc } from '../utils/trpc';
export default function IndexPage() {
  const hello = trpc.hello.useQuery({ text: 'client' });
  if (!hello.data) {
    return <div>Loading...</div>;
  }
  return (
    <div>
      <p>{hello.data.greeting}</p>
    </div>
  );
}

Alternativ för `createTRPCNext()`

`config`-callback

config-argumentet är en funktion som returnerar ett objekt som konfigurerar tRPC- och React Query-klienterna. Denna funktion har ett ctx-input som ger dig tillgång till Next.js req-objektet bland annat. Returvärdet kan innehålla följande egenskaper:

Obligatoriskt:
links för att anpassa dataflödet mellan tRPC-klient och tRPC-server. Läs mer.
Valfritt:
queryClientConfig: ett konfigurationsobjekt för React Query's QueryClient som används internt av tRPC React-hooks: QueryClient docs
queryClient: en React Query QueryClient-instans
- Obs: Du kan bara ange antingen queryClient eller queryClientConfig.
transformer: en transformer som appliceras på utgående payloads. Läs mer om Data Transformers
abortOnUnmount: avgör om pågående förfrågningar ska avbrytas när komponenten avmonteras. Standardvärdet är false.

`overrides`: (standard: `undefined`)

Konfigurera överskrivningar för React Query's hooks.

`ssr`-boolean (standard: `false`)

Anger om tRPC ska avvakta queries vid server-side rendering av en sida. Standard är false.

`responseMeta`-callback

Möjlighet att sätta request headers och HTTP-status vid server-side rendering.

Exempel

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
});

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
});

Nästa steg

Bläddra igenom resten av dokumentationen för att lära dig mer om ämnen som auktorisering, middlewares och felhantering.

Du kan också hitta information om queries och mutations nu när du använder @trpc/react-query.

Rekommenderad filstruktur​

Lägg till tRPC i befintligt Next.js-projekt​

1. Installera beroenden​

2. Aktivera strikt läge​

3. Skapa en tRPC-router​

4. Skapa tRPC-hooks​

5. Konfigurera _app.tsx​

6. Gör en API-förfrågan​

Alternativ för createTRPCNext()​

config-callback​

overrides: (standard: undefined)​

ssr-boolean (standard: false)​

responseMeta-callback​

Exempel​

Nästa steg​