t3-stack

T3 Stack Best Practices

Overview

Layer	Technology	Purpose
Framework	Next.js 15	Full-stack React framework
API	tRPC	End-to-end typesafe APIs
Database	Prisma	Type-safe ORM
Styling	Tailwind CSS	Utility-first CSS
Auth	NextAuth.js / Auth.js	Authentication
Language	TypeScript	Strict type safety

Related rules: nextjs-15.mdc, typescript.mdc, tailwind.mdc

---

Project Structure

src/
├── app/                    # Next.js App Router
│   ├── _components/        # Route-specific components
│   ├── api/
│   │   └── trpc/
│   │       └── [trpc]/
│   │           └── route.ts
│   ├── layout.tsx
│   └── page.tsx
├── server/
│   ├── api/
│   │   ├── routers/        # tRPC routers
│   │   │   ├── post.ts
│   │   │   └── user.ts
│   │   ├── root.ts         # Root router
│   │   └── trpc.ts         # tRPC context & procedures
│   └── db.ts               # Prisma client
├── trpc/
│   ├── react.tsx           # React Query integration
│   └── server.ts           # Server-side caller
├── lib/
│   └── utils.ts
└── env.js                  # Environment validation
prisma/
└── schema.prisma           # Database schema

---

tRPC Setup

Server Context

// src/server/api/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server'
import { type Session } from 'next-auth'
import superjson from 'superjson'
import { ZodError } from 'zod'
import { db } from '@/server/db'
import { getServerAuthSession } from '@/server/auth'

interface CreateContextOptions {
  session: Session | null
}

export const createInnerTRPCContext = (opts: CreateContextOptions) => {
  return {
    session: opts.session,
    db,
  }
}

export const createTRPCContext = async (opts: { headers: Headers }) => {
  const session = await getServerAuthSession()
  return createInnerTRPCContext({ session })
}

const t = initTRPC.context<typeof createTRPCContext>().create({
  transformer: superjson,
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError: error.cause instanceof ZodError ? error.cause.flatten() : null,
      },
    }
  },
})

export const createTRPCRouter = t.router
export const publicProcedure = t.procedure