Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-fullstack-nextjs-trpc-drizzle

tpl-fullstack-nextjs-trpc-drizzle

Verified

Template do pack (fullstack/05-nextjs-trpc-drizzle.md). Orienta o agente em stacks fullstack e arquitetura ponta a ponta alinhado a esse contexto.

PROJECT: Next.js 15 + tRPC v11 + Drizzle + Neon + NextAuth v5

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: fullstack/05-nextjs-trpc-drizzle.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

STACK

  • Framework: Next.js 15 (App Router, React 19)
  • API: tRPC v11
  • ORM: Drizzle ORM + Neon (PostgreSQL serverless)
  • Auth: Auth.js v5 (NextAuth v5)
  • UI: shadcn/ui + Tailwind CSS v3
  • Language: TypeScript 5.x (strict)
  • Testing: Vitest + Playwright

PROJECT STRUCTURE

src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── (auth)/
│   │   ├── login/page.tsx
│   │   └── signup/page.tsx
│   ├── (dashboard)/
│   │   └── dashboard/page.tsx
│   └── api/
│       ├── auth/
│       │   └── [...nextauth]/route.ts
│       └── trpc/
│           └── [trpc]/route.ts
├── server/
│   ├── auth.ts                 # NextAuth v5 config
│   ├── db/
│   │   ├── index.ts            # Drizzle + Neon client
│   │   └── schema.ts
│   └── api/
│       ├── root.ts
│       ├── trpc.ts             # Context, procedures
│       └── routers/
│           ├── post.ts
│           └── user.ts
├── trpc/
│   ├── react.tsx               # React client provider
│   └── server.ts               # RSC caller
└── components/
    └── ui/                     # shadcn components

ARCHITECTURE RULES

  1. App Router + tRPC coexist cleanly — Server Components call createCaller(ctx); Client Components use trpc.* hooks.
  2. Drizzle schema files are the only migration source — drizzle-kit push for dev, drizzle-kit migrate for prod.
  3. Auth.js v5 callbacks enrich JWT — add userId and role to session/token in jwt callback.
  4. Neon serverless driver used in edge — use @neondatabase/serverless + ws polyfill for edge runtime; Pool for Node runtime.
  5. No mixing RSC data fetching and tRPC — choose per-page: RSC direct call or Client hook; don't nest both patterns.
  6. protectedProcedure = session check — automatically redirects or throws UNAUTHORIZED.
  7. shadcn components are local — never update shadcn by overwriting; treat as owned files.

TRPC + APP ROUTER SETUP

// src/server/api/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server'
import { cache }    from 'react'
import superjson    from 'superjson'
import { auth }     from '../auth'
import { db }       from '../db'

export const createTRPCContext = cache(async () => {
  const session = await auth()
  return { db, session }
})

const t = initTRPC.context<typeof createTRPCContext>().create({
  transformer: superjson,
})

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

export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
  if (!ctx.session?.user?.id) throw new TRPCError({ code: 'UNAUTHORIZED' })
  return next({ ctx: { ...ctx, session: ctx.session } })
})

// src/app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
import { appRouter }           from '~/server/api/root'
import { createTRPCContext }   from '~/server/api/trpc'

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: createTRPCContext,
  })

export { handler as GET, handler as POST }

DRIZZLE + NEON SETUP

// src/server/db/schema.ts
import { pgTable, text, boolean, timestamp, integer } from 'drizzle-orm/pg-core'
import { relations } from 'drizzle-orm'
import { createId }  from '@paralleldrive/cuid2'

export const users = pgTable('users', {
  id:            text('id').primaryKey().$defaultFn(createId),
  name:          text('name'),
  email:         text('email').notNull().unique(),
  emailVerified: timestamp('email_verified', { mode: 'date' }),
  image:         text('image'),
  role:          text('role', { enum: ['user', 'admin'] }).notNull().default('user'),
})

export const posts = pgTable('posts', {
  id:        text('id').primaryKey().$defaultFn(createId),
  title:     text('title').notNull(),
  content:   text('content').notNull(),
  published: boolean('published').notNull().default(false),
  authorId:  text('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  createdAt: timestamp('created_at', { mode: 'date' }).defaultNow(),
})

export const usersRelations = relations(users, ({ many }) => ({ posts: many(posts) }))
export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, { fields: [posts.authorId], references: [users.id] }),
}))

// src/server/db/index.ts
import { neon }    from '@neondatabase/serverless'
import { drizzle } from 'drizzle-orm/neon-http'
import * as schema from './schema'

const sql = neon(process.env.DATABASE_URL!)
export const db = drizzle(sql, { schema })
export type DB  = typeof db

RSC + CLIENT HYBRID USAGE

// src/trpc/server.ts (RSC side - no HTTP round trip)
import { createCallerFactory } from '~/server/api/root'
import { createTRPCContext }   from '~/server/api/trpc'

const createCaller = createCallerFactory(appRouter)
export const api = createCaller(await createTRPCContext())

// src/app/(dashboard)/dashboard/page.tsx — SERVER COMPONENT
import { api } from '~/trpc/server'

export default async function DashboardPage() {
  const posts = await api.post.list({ limit: 10 })
  // posts is fully typed from router return type
  return <PostList initialPosts={posts} />
}

// src/components/PostList.tsx — CLIENT COMPONENT (optimistic updates)
'use client'
import { trpc } from '~/trpc/react'

export function PostList({ initialPosts }: { initialPosts: Post[] }) {
  const { data: posts } = trpc.post.list.useQuery(
    { limit: 10 },
    { initialData: initialPosts }         // hydrate from RSC
  )

  const utils = trpc.useUtils()
  const create = trpc.post.create.useMutation({
    onMutate: async (newPost) => {
      await utils.post.list.cancel()
      const prev = utils.post.list.getData({ limit: 10 })
      utils.post.list.setData({ limit: 10 }, (old) =>
        old ? [{ ...newPost, id: 'temp', createdAt: new Date() }, ...old] : old
      )
      return { prev }
    },
    onError: (_, __, ctx) => utils.post.list.setData({ limit: 10 }, ctx?.prev),
    onSettled: () => utils.post.list.invalidate(),
  })

  return <ul>{posts?.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

NEXTAUTH V5 CONFIG

// src/server/auth.ts
import NextAuth, { type DefaultSession } from 'next-auth'
import GitHub   from 'next-auth/providers/github'
import Credentials from 'next-auth/providers/credentials'
import { DrizzleAdapter } from '@auth/drizzle-adapter'
import { db } from './db'

declare module 'next-auth' {
  interface Session { user: { id: string; role: 'user' | 'admin' } & DefaultSession['user'] }
}

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: DrizzleAdapter(db),
  providers: [GitHub],
  callbacks: {
    session: ({ session, user }) => ({
      ...session,
      user: { ...session.user, id: user.id, role: (user as typeof user & { role: string }).role ?? 'user' },
    }),
  },
  pages: { signIn: '/login' },
})

ROUTING TABLE

Procedure / RouteTypeAuthAction
post.listtRPC queryNoPaginated posts
post.byIdtRPC queryNoSingle post
post.createtRPC mutationYesCreate post
post.publishtRPC mutationYes (owner)Publish post
post.deletetRPC mutationYes (owner)Delete post
user.metRPC queryYesCurrent user
user.updatetRPC mutationYesUpdate profile
GET /api/auth/[...nextauth]HTTP—Auth endpoints
GET /dashboardRSC pageYesDashboard with RSC prefetch
GET /loginClient pageNoAuth.js sign-in

QUALITY GATES

  • tsc --noEmit — zero errors
  • next build — zero warnings
  • RSC pages prefetch via api.* caller (no waterfall)
  • Client mutations use optimistic updates for UX
  • NextAuth session type augmented with id and role
  • drizzle-kit check — migrations synced with schema
  • vitest run — all unit tests pass
  • playwright test — login + create post E2E passes
  • Neon connection string in .env.local, never committed

FORBIDDEN

  • ❌ fetch('/api/trpc/...') from Client Components — use tRPC hooks
  • ❌ "use client" on layout or page components that can be RSC
  • ❌ any on tRPC return types or Drizzle query results
  • ❌ Multiple Drizzle/Neon client instances
  • ❌ useEffect for data loading — use tRPC hooks or RSC
  • ❌ session.user.id without type augmentation
  • ❌ Drizzle raw SQL without parameterization
  • ❌ Environment variables without NEXT_PUBLIC_ prefix accessed on client
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall