name	stack-knowledge
description	Project technology stack patterns for Next.js + Neon Postgres + Drizzle ORM + Better Auth + Tailwind CSS
user-invocable	false

Stack Knowledge

This skill provides stack-specific patterns for agents making architectural and implementation decisions.

Use @neondatabase/serverless driver with Drizzle ORM
Connection: DATABASE_URL env var pointing to Neon's pooled connection string
Neon branching: each Vercel preview deployment can get its own database branch
No Row-Level Security — authorization happens in the application layer via Better Auth middleware
Migrations: drizzle-kit push for development, drizzle-kit migrate for production
Always use connection pooling in serverless environments

All database access goes through Drizzle — no raw SQL in application code
Define schemas in src/db/schema/ with one file per entity
Index every column used in WHERE, JOIN, or ORDER BY
Use partial indexes when filtering on constant conditions (e.g., status = 'active')
Infer types from schema: type User = typeof users.$inferSelect

Configure with Drizzle adapter pointing at Neon
After adding/changing plugins, always run: npx @better-auth/cli@latest generate
Import plugins from dedicated paths: import { twoFactor } from "better-auth/plugins/two-factor"
Infer session types: typeof auth.$Infer.Session
Environment variables: BETTER_AUTH_SECRET, BETTER_AUTH_URL
Server-side auth: auth.api.getSession()

Server Components by default — only add "use client" for interactivity/hooks/browser APIs
Server actions for mutations, route handlers for webhooks/external integrations
Parallel data fetching with Promise.all() — never sequential awaits
Wrap async server components in <Suspense> with meaningful fallbacks
Dynamic imports via next/dynamic for heavy components not needed on first paint