T3 Stack Gotcha: Stale Prisma Client After Migration

The T3 Stack is not a framework — it's a curated set of tools that together provide end-to-end type safety from database to browser. Each tool solves a specific problem: Next.js for rendering and routing, tRPC for type-safe APIs, Prisma for type-safe database access, Tailwind for styling, and TypeScript as the connective tissue.

In 2026, T3 has split into two main patterns: (1) RSC-first: Server Components read directly from Prisma with Server Actions for writes (zero network hop), and (2) tRPC-everywhere: classic T3 with tRPC for both reads and writes. This guide covers pattern #2 because it is still the default create-t3-app setup, but we’ll clearly call out where the RSC-first pattern wins.

The 2026 iteration has evolved significantly. Next.js 15/16’s App Router with Server Components changes where data fetching happens. tRPC v11 integrates natively with TanStack Query for caching and optimistic updates. Prisma’s edge runtime makes serverless deployments viable. shadcn/ui replaces bloated component libraries with copy-paste components you fully own.

This guide covers the architecture decisions, the type chain that makes the stack powerful, the production pitfalls that catch teams off guard, and the migration path from earlier versions.

The Type Chain: How the T3 Stack Propagates Types End-to-End

The T3 Stack's core value proposition is the type chain — a single change to your database schema propagates type safety through every layer of your application without manual synchronization.

It starts with Prisma's schema.prisma. When you define a model, Prisma generates a TypeScript client where every query is typed against your schema. The output of a Prisma query is a typed object that flows into your tRPC procedure. tRPC infers the procedure's output type from the return value. On the client, tRPC's useQuery hook infers the response type from the procedure definition. React components receive typed props from the tRPC response.

The chain: schema.prisma → Prisma Client types → tRPC procedure types → React component props. One change at the top propagates to the bottom. If you rename a column, TypeScript catches every reference that's now broken — in your API layer, your frontend components, and your form validations.

tRPC v11: Type-Safe APIs Without Code Generation

tRPC v11 eliminates the manual synchronization between backend API definitions and frontend type expectations. You define a procedure (query or mutation) on the server with a zod input schema and a typed resolver. The client imports the router type and gets full autocompletion, compile-time type checking, and zero code generation.

The v11 improvements over v10 include native TanStack Query v5 integration, better error handling with typed TRPCError responses, and improved middleware composition. The httpBatchLink now supports streaming — multiple procedures in a single HTTP request with progressive response delivery.

The key architectural decision is router composition. You define separate routers for each domain (users, posts, comments) and merge them into a root appRouter. The client sees a flat API surface: trpc.users.getById.useQuery() — the router hierarchy is invisible on the client side.

Prisma: Type-Safe Database Access in the Edge Runtime Era

Prisma generates a TypeScript client from your schema.prisma file. Every query — findMany, create, update, delete — is typed against your actual database schema. If you rename a column, TypeScript catches every query that references the old name at compile time.

The 2026 evolution is Prisma's edge runtime support. Traditional Prisma requires a Node.js binary for database connections — incompatible with edge runtimes (Cloudflare Workers, Vercel Edge Functions). Prisma's driver adapters (for Neon, PlanetScale, Turso) enable edge-compatible database access by using platform-native drivers instead of Prisma's binary engine.

The architectural decision is connection pooling. In serverless/edge environments, each function invocation opens a new database connection. Without pooling, you exhaust the database's connection limit at ~100 concurrent requests. Prisma Accelerate or a database-native pooler (PgBouncer, Neon's built-in pooler) is mandatory for production serverless deployments.

shadcn/ui: Owning Your Component Code Instead of Depending on It

shadcn/ui is not a component library — it's a collection of copy-paste components built on Radix UI primitives and styled with Tailwind CSS. You run npx shadcn-ui@latest add button and the component source code is copied into your project. You own it. You modify it. There's no version-locked dependency to update.

This solves a real production problem: traditional component libraries (MUI, Ant Design, Chakra) ship as npm packages. When you need to customize a component beyond the library's API surface, you fight the abstraction. shadcn/ui gives you the source code — customization is just editing a file in your project.

The architecture is built on three layers: Radix UI provides accessible primitives (keyboard navigation, ARIA attributes, focus management), Tailwind CSS provides the styling system (utility classes, CSS variables for theming), and shadcn/ui provides the composition layer that combines them into production-ready components.

Project Structure: Organizing the T3 Stack for Scale

The T3 Stack's project structure determines how maintainable the codebase is at scale. A flat structure works for prototypes but collapses at 50+ procedures and 100+ components. The recommended structure separates concerns by domain, not by technology layer.

The key organizational principle is domain-driven: each feature (users, posts, comments) gets its own directory containing its Prisma model, tRPC router, Server Components, Client Components, and shared types. This keeps related code together — when you modify the posts feature, everything you need is in one directory.

The alternative — organizing by technology layer (all routers in one directory, all components in another) — forces you to jump between 5 directories to understand a single feature. At scale, this cognitive overhead slows development to a crawl.

Frequently Asked Questions