Version: 10.x

Konfigurera med Next.js

Inofficiell Beta-översättning

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

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

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

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

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

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

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

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

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

sh
bun add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@4 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/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/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/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/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/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/ssr
   **/
  ssr: false,
});

notering

createTRPCNext fungerar inte med tRPC-v9:s interopläge. Om du migrerar från v9 med interop 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`-funktionen

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:s React-hooks: QueryClient-dokumentation
queryClient: en React Query QueryClient-instans
- Observera: Du kan bara ange antingen en queryClient eller en 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`-funktionen

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) {
    /* [...] */
  },
  ssr: true,
  responseMeta(opts) {
    const { clientErrors } = opts;
    if (clientErrors.length) {
      // propagate first http error from API calls
      return {
        status: clientErrors[0].data?.httpStatus ?? 500,
      };
    }
    // cache full page for 1 day + revalidate once every second
    const ONE_DAY_IN_SECONDS = 60 * 60 * 24;
    return {
      'Cache-Control': `s-maxage=1, stale-while-revalidate=${ONE_DAY_IN_SECONDS}`,
    };
  },
});

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
  ssr: true,
  responseMeta(opts) {
    const { clientErrors } = opts;
    if (clientErrors.length) {
      // propagate first http error from API calls
      return {
        status: clientErrors[0].data?.httpStatus ?? 500,
      };
    }
    // cache full page for 1 day + revalidate once every second
    const ONE_DAY_IN_SECONDS = 60 * 60 * 24;
    return {
      'Cache-Control': `s-maxage=1, stale-while-revalidate=${ONE_DAY_IN_SECONDS}`,
    };
  },
});

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-funktionen​

overrides: (standard: undefined)​

ssr-boolean (standard: false)​

responseMeta-funktionen​

Exempel​

Nästa steg​