CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-trpc--next

Next.js integration for tRPC that enables end-to-end type-safe APIs with enhanced server-side rendering and static site generation capabilities.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@trpc/next

@trpc/next is the Next.js integration library for tRPC that enables end-to-end type-safe APIs with enhanced server-side rendering and static site generation capabilities. It provides seamless client-server communication through React Query integration, automatic provider configuration, and comprehensive support for Next.js features including SSR, SSG, and client-side hydration.

Package Information

  • Package Name: @trpc/next
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @trpc/next @trpc/react-query @tanstack/react-query

Core Imports

import { createTRPCNext, withTRPC } from "@trpc/next";
import { ssrPrepass } from "@trpc/next/ssrPrepass";

For specific App Router features:

import { experimental_createTRPCNextAppDirClient } from "@trpc/next/app-dir/client";
import { experimental_createTRPCNextAppDirServer } from "@trpc/next/app-dir/server";
import { experimental_nextCacheLink } from "@trpc/next/app-dir/links/nextCache";
import { experimental_nextHttpLink } from "@trpc/next/app-dir/links/nextHttp";

Basic Usage

Pages Router Setup

import { createTRPCNext } from "@trpc/next";
import { httpBatchLink } from "@trpc/client";
import type { AppRouter } from "../pages/api/[trpc]";

export const trpc = createTRPCNext<AppRouter>({
  config() {
    return {
      links: [
        httpBatchLink({
          url: "http://localhost:3000/api/trpc",
        }),
      ],
    };
  },
  ssr: false,
});

// In _app.tsx
const App = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};

export default trpc.withTRPC(App);

Using tRPC in Components

import { trpc } from "~/utils/trpc";

export function UserProfile() {
  const { data, error, status } = trpc.user.getProfile.useQuery({
    userId: "123",
  });

  if (error) return <p>Error: {error.message}</p>;
  if (status !== "success") return <p>Loading...</p>;

  return <div>Welcome, {data.name}!</div>;
}

Architecture

@trpc/next is built around several key architectural components:

  • Pages Router Integration: Traditional Next.js pages with withTRPC HOC and createTRPCNext factory
  • App Router Support: Experimental features for Next.js App Router with server components and server actions
  • SSR Engine: Server-side rendering support with automatic query prefetching and hydration
  • Cache Management: Integration with Next.js caching strategies and revalidation
  • Type Safety: End-to-end TypeScript integration preserving types from server to client
  • React Query Integration: Built on @tanstack/react-query for caching and synchronization

Capabilities

Pages Router Integration

Core integration for Next.js Pages Router providing HOC wrapping and tRPC hook creation. Essential for traditional Next.js applications.

function createTRPCNext<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext>(
  opts: WithTRPCNoSSROptions<TRouter> | WithTRPCSSROptions<TRouter>
): CreateTRPCNext<TRouter, TSSRContext>;

function withTRPC<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext>(
  opts: WithTRPCNoSSROptions<TRouter> | WithTRPCSSROptions<TRouter>
): (AppOrPage: NextComponentType<any, any, any>) => NextComponentType;

Pages Router Integration

Server-Side Rendering (SSR)

Advanced SSR capabilities with automatic query prefetching, cache dehydration/hydration, and response meta handling.

export const ssrPrepass: TRPCPrepassHelper;

interface WithTRPCSSROptions<TRouter extends AnyRouter> extends WithTRPCOptions<TRouter> {
  ssr: true | ((opts: { ctx: NextPageContext }) => boolean | Promise<boolean>);
  responseMeta?: (opts: {
    ctx: NextPageContext;
    clientErrors: TRPCClientError<TRouter>[];
  }) => ResponseMeta;
  ssrPrepass: TRPCPrepassHelper;
}

Server-Side Rendering

App Router Support

Experimental features for Next.js App Router including server components, server actions, and advanced caching.

function experimental_createTRPCNextAppDirClient<TRouter extends AnyRouter>(
  opts: CreateTRPCNextAppRouterOptions<TRouter>
): TRPCClient<TRouter>;

function experimental_createTRPCNextAppDirServer<TRouter extends AnyRouter>(
  opts: CreateTRPCNextAppRouterOptions<TRouter>
): NextAppDirDecorateRouterRecord<TRouter['_def']['_config']['$types'], TRouter['_def']['record']>;

App Router Support

Server Actions

Experimental server actions integration for form handling and mutations in App Router.

function experimental_createActionHook<TInferrable extends InferrableClientTypes>(
  opts: CreateTRPCClientOptions<TInferrable>
): <TDef extends ActionHandlerDef>(
  handler: TRPCActionHandler<TDef>,
  useActionOpts?: UseTRPCActionOptions<TDef>
) => UseTRPCActionResult<TDef>;

function experimental_createServerActionHandler<TInstance extends { _config: RootConfig<AnyRootTypes> }>(
  t: TInstance,
  opts: CreateContextCallback & ServerActionHandlerOptions
): <TProc extends AnyProcedure>(proc: TProc) => TRPCActionHandler<inferActionDef<TInstance, TProc>>;

Server Actions

Cache Links

Specialized tRPC links for Next.js caching integration with cache tags and revalidation.

function experimental_nextCacheLink<TRouter extends AnyRouter>(
  opts: NextCacheLinkOptions<TRouter>
): TRPCLink<TRouter>;

function experimental_nextHttpLink<TRouter extends AnyRouter>(
  opts: NextLinkSingleOptions<TRouter['_def']['_config']['$types']> | NextLinkBatchOptions<TRouter['_def']['_config']['$types']>
): TRPCLink<TRouter>;

Cache Links

Core Types

// Base router type from tRPC
interface AnyRouter {
  _def: {
    _config: {
      $types: any;
    };
    record: any;
  };
}

// Next.js page context type
interface NextPageContext {
  req?: IncomingMessage;
  res?: ServerResponse;
  pathname: string;
  query: ParsedUrlQuery;
  asPath?: string;
}

// Configuration options for withTRPC HOC
interface WithTRPCConfig<TRouter extends AnyRouter> extends CreateTRPCClientOptions<TRouter>, CreateTRPCReactQueryClientConfig {
  abortOnUnmount?: boolean;
}

// Return type from createTRPCNext with decorated router and utilities
interface CreateTRPCNext<TRouter extends AnyRouter, TSSRContext extends NextPageContext> {
  useContext(): CreateReactUtils<TRouter, TSSRContext>;
  useUtils(): CreateReactUtils<TRouter, TSSRContext>;
  withTRPC: ReturnType<typeof withTRPC<TRouter, TSSRContext>>;
  useQueries: TRPCUseQueries<TRouter>;
  useSuspenseQueries: TRPCUseSuspenseQueries<TRouter>;
}

// Props passed during SSR prepass phase
interface TRPCPrepassProps<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext> {
  config: WithTRPCConfig<TRouter>;
  queryClient: QueryClient;
  trpcClient: TRPCUntypedClient<TRouter> | TRPCClient<TRouter>;
  ssrState: 'prepass';
  ssrContext: TSSRContext;
}

// Function signature for SSR prepass helpers
type TRPCPrepassHelper = (opts: {
  parent: WithTRPCSSROptions<AnyRouter>;
  WithTRPC: NextComponentType<any, any, any>;
  AppOrPage: NextComponentType<any, any, any>;
}) => void;

// App Router configuration options
interface CreateTRPCNextAppRouterOptions<TRouter extends AnyRouter> {
  config: () => CreateTRPCClientOptions<TRouter>;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@trpc/next@11.5.x
Publish Source
CLI
Badge
tessl/npm-trpc--next badge