tRPC v11 with Next.js 15: End-to-End Type Safety, Server Actions & TanStack Query v5

// src/server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { ZodError } from 'zod';
import superjson from 'superjson';
import { type NextRequest } from 'next/server';

interface CreateContextOptions {
  headers: Headers;
  // Add any other context properties you need, e.g., session
  userId?: string;
}

/**
 * This is the actual context you'll use in your router. It will be used to process every request
 * that goes through your tRPC router.
 */
export const createTRPCContext = async (opts: CreateContextOptions) => {
  // Simulate authentication or session retrieval
  const userId = opts.headers.get('x-user-id') || undefined; // Example: get from header
  return {
    headers: opts.headers,
    userId,
  };
};

/**
 * Initializer for tRPC.
 * @see https://trpc.io/docs/v11/server/initialization
 */
const t = initTRPC.context<typeof createTRPCContext>().transformer(superjson).create({
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError:
          error.code === 'BAD_REQUEST' && error.cause instanceof ZodError
            ? error.cause.flatten()
            : null,
      },
    };
  },
});

/**
 * Reusable middleware that enforces users are logged in.
 */
const enforceUserIsAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.userId) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({
    ctx: {
      // Infers a new type for the context with `userId` now being non-nullable
      userId: ctx.userId,
    },
  });
});

/**
 * Export reusable router and procedure helpers
 */
export const createTRPCRouter = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(enforceUserIsAuthed);

// src/server/routers/_app.ts
import { z } from 'zod';
import { createTRPCRouter, publicProcedure, protectedProcedure } from '../trpc';

// Example: Simulate a database
const posts: { id: string; title: string; content: string; authorId: string }[] = [];

export const appRouter = createTRPCRouter({
  post: createTRPCRouter({
    getById: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => {
        const post = posts.find(p => p.id === input.id);
        if (!post) {
          throw new TRPCError({ code: 'NOT_FOUND', message: 'Post not found' });
        }
        return post;
      }),
    create: protectedProcedure
      .input(z.object({ title: z.string().min(1), content: z.string().min(1) }))
      .mutation(({ input, ctx }) => {
        const newPost = {
          id: Math.random().toString(36).substring(2, 9),
          title: input.title,
          content: input.content,
          authorId: ctx.userId, // userId is guaranteed to be present by protectedProcedure
        };
        posts.push(newPost);
        return newPost;
      }),
    getAll: publicProcedure
      .query(() => {
        return posts;
      }),
  }),
  user: createTRPCRouter({
    getProfile: protectedProcedure
      .query(({ ctx }) => {
        // In a real app, fetch user profile from DB using ctx.userId
        return { id: ctx.userId, name: `User ${ctx.userId}` };
      }),
  }),
});

// Export type definition of API
export type AppRouter = typeof appRouter;

// src/app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/routers/_app';
import { createTRPCContext } from '@/server/trpc';
import { type NextRequest } from 'next/server';

/**
 * This wraps the `createTRPCContext` helper and provides the required context for the tRPC API when
 * handling a HTTP request (e.g., when you make requests from the client).
 */
const createContext = async (req: NextRequest) => {
  return createTRPCContext({
    headers: req.headers,
  });
};

const handler = (req: NextRequest) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: () => createContext(req),
    onError({ error, path }) {
      console.error(`❌ tRPC failed on ${path ?? '<no-path>'}: ${error.message}`);
    },
  });

export { handler as GET, handler as POST };

// src/trpc/react.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink, loggerLink } from '@trpc/client';
import { createTRPCReact } from '@trpc/react-query';
import { useState } from 'react';
import superjson from 'superjson';

import { type AppRouter } from '@/server/routers/_app';

const createQueryClient = () => new QueryClient({
  defaultOptions: {
    queries: {
      // With SSR, we usually want to set some default staleTime
      // above 0 to avoid refetching on first mount.
      staleTime: 60 * 1000,
    },
  },
});

let clientQueryClient: QueryClient | undefined = undefined;
const getQueryClient = () => {
  if (typeof window === 'undefined') {
    // Server: always make a new query client
    return createQueryClient();
  } else {
    // Browser: make a new query client if we don't already have one
    // This is to make sure we use the same query client across the entire browser session
    return (clientQueryClient ??= createQueryClient());
  }
};

export const api = createTRPCReact<AppRouter>();

export function TRPCReactProvider(props: { children: React.ReactNode }) {
  const queryClient = getQueryClient();

  const [trpcClient] = useState(() =>
    api.createClient({
      links: [
        loggerLink({
          enabled: (op) =>
            process.env.NODE_ENV === 'development' ||
            (op.direction === 'down' && op.result instanceof Error),
        }),
        httpBatchLink({
          url: '/api/trpc', // Relative path for Next.js API routes
          transformer: superjson,
        }),
      ],
    }),
  );

  return (
    <QueryClientProvider client={queryClient}>
      <api.Provider client={trpcClient} queryClient={queryClient}>
        {props.children}
      </api.Provider>
    </QueryClientProvider>
  );
}

// src/app/layout.tsx
import { TRPCReactProvider } from '@/trpc/react';
import './globals.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <TRPCReactProvider>{children}</TRPCReactProvider>
      </body>
    </html>
  );
}

// src/app/actions.ts
'use server';

import { z } from 'zod';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

// Simulate a database for Server Actions
const serverActionPosts: { id: string; title: string; content: string }[] = [];

const createPostSchema = z.object({
  title: z.string().min(1, 'Title is required'),
  content: z.string().min(1, 'Content is required'),
});

export async function createPostAction(prevState: any, formData: FormData) {
  const rawFormData = {
    title: formData.get('title'),
    content: formData.get('content'),
  };

  const validatedFields = createPostSchema.safeParse(rawFormData);

  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
      message: 'Failed to create post.',
    };
  }

  const { title, content } = validatedFields.data;

  // Simulate DB operation
  const newPost = {
    id: Math.random().toString(36).substring(2, 9),
    title,
    content,
  };
  serverActionPosts.push(newPost);

  // Revalidate paths to show new data
  revalidatePath('/server-actions-posts');
  redirect('/server-actions-posts'); // Redirect after successful creation

  return { message: 'Post created successfully.' };
}

export async function getPostsAction() {
  // Simulate fetching posts
  return serverActionPosts;
}

// src/app/page.tsx
import { api } from '@/trpc/react';
import { createPostAction, getPostsAction } from './actions';
import { PostForm } from './post-form'; // A client component for the form

export default async function HomePage() {
  // Fetch posts using tRPC on the server (SSR)
  const trpcPosts = await api.ssr.post.getAll.fetch();

  // Fetch posts using Server Action on the server (SSR)
  const serverActionPosts = await getPostsAction();

  return (
    <main className="p-4">
      <h1 className="text-2xl font-bold mb-4">Full-Stack Type Safety with tRPC & Server Actions</h1>

      <section className="mb-8">
        <h2 className="text-xl font-semibold mb-2">tRPC Posts (SSR)</h2>
        <ul className="list-disc pl-5">
          {trpcPosts.map((post) => (
            <li key={post.id}>
              <strong>{post.title}</strong> by {post.authorId}
              <p className="text-sm text-gray-600">{post.content}</p>
            </li>
          ))}
        </ul>
      </section>

      <section className="mb-8">
        <h2 className="text-xl font-semibold mb-2">Server Action Posts (SSR)</h2>
        <ul className="list-disc pl-5">
          {serverActionPosts.map((post) => (
            <li key={post.id}>
              <strong>{post.title}</strong>
              <p className="text-sm text-gray-600">{post.content}</p>
            </li>
          ))}
        </ul>
      </section>

      <section className="mb-8">
        <h2 className="text-xl font-semibold mb-2">Create Post (tRPC Mutation - Client)</h2>
        <CreateTRPCPostForm />
      </section>

      <section>
        <h2 className="text-xl font-semibold mb-2">Create Post (Server Action - Client)</h2>
        <PostForm /> {/* This component uses `useFormState` and `createPostAction` */}
      </section>
    </main>
  );
}

// Client component for tRPC mutation
function CreateTRPCPostForm() {
  const createPost = api.post.create.useMutation({
    onSuccess: () => {
      // Invalidate cache to refetch all posts after successful creation
      api.post.getAll.invalidate();
      alert('tRPC Post created!');
    },
    onError: (error) => {
      alert(`Error creating tRPC post: ${error.message}`);
    },
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const title = formData.get('title') as string;
    const content = formData.get('content') as string;
    createPost.mutate({ title, content });
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <div>
        <label htmlFor="trpc-title" className="block text-sm font-medium text-gray-700">Title</label>
        <input type="text" id="trpc-title" name="title" required className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" />
      </div>
      <div>
        <label htmlFor="trpc-content" className="block text-sm font-medium text-gray-700">Content</label>
        <textarea id="trpc-content" name="content" required className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2"></textarea>
      </div>
      <button type="submit" disabled={createPost.isLoading} className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50">
        {createPost.isLoading ? 'Creating...' : 'Create tRPC Post'}
      </button>
    </form>
  );
}

// src/app/post-form.tsx
'use client';

import { useFormState, useFormStatus } from 'react-dom';
import { createPostAction } from './actions';

const initialState = {
  message: '',
  errors: undefined,
};

export function PostForm() {
  const [state, formAction] = useFormState(createPostAction, initialState);
  const { pending } = useFormStatus();

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <label htmlFor="sa-title" className="block text-sm font-medium text-gray-700">Title</label>
        <input type="text" id="sa-title" name="title" required className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" />
        {state.errors?.title && (
          <p className="text-red-500 text-xs mt-1">{state.errors.title.join(', ')}</p>
        )}
      </div>
      <div>
        <label htmlFor="sa-content" className="block text-sm font-medium text-gray-700">Content</label>
        <textarea id="sa-content" name="content" required className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2"></textarea>
        {state.errors?.content && (
          <p className="text-red-500 text-xs mt-1">{state.errors.content.join(', ')}</p>
        )}
      </div>
      <button type="submit" disabled={pending} className="px-4 py-2 bg-green-600 text-white rounded-md hover:bg-green-700 disabled:opacity-50">
        {pending ? 'Creating...' : 'Create Server Action Post'}
      </button>
      {state.message && <p className="mt-2 text-sm text-green-600">{state.message}</p>}
    </form>
  );
}