Cursor Rules Template: Next.js T3 Stack with TRPC, Prisma, NextAuth

Overview

The Cursor rules configuration for this page defines a concrete, reusable set of AI-driven guidelines tailored to building a secure Next.js 13+ (T3 stack) application with TRPC, Prisma, and NextAuth. It targets developers implementing a full-stack with a modern React-based frontend, strongly-typed server routes, and robust authentication patterns using Cursor AI as a companion to your codebase.

When to Use These Cursor Rules

• Starting a new Next.js project with the T3 stack (TRPC, Prisma, NextAuth) and a need for consistent AI guidance.
• Setting up TRPC routers and Prisma ORM interactions with strict typing and runtime safety checks.
• Enforcing secure authentication flows using NextAuth and JWT sessions in both server and client layers.
• Embedding Cursor AI rules into CI pipelines to maintain code quality and security across dev, staging, and production.
• Documenting architecture decisions, directory layout, and testing strategies for a team.

Copyable .cursorrules Configuration

cursor_rules_v1:
  framework: 'Next.js (T3 Stack) with TRPC, Prisma, NextAuth'
  role: 'Framework Engineer'
  context: 'You are Cursor AI, guiding the implementation of a robust Next.js 13+ app using the T3 stack. Focus on type-safety, secure auth, and scalable API design.'
  style:
    language: 'TypeScript'
    linting: 'ESLint + Prettier with strict rules'
  architecture:
    root: '.'
    apps: ['apps/web']
    packages: ['packages/server', 'packages/db', 'packages/ui']
    prisma: 'prisma/'
  auth:
    strategy: 'NextAuth.js with JWT sessions'
    providers: ['Google', 'GitHub', 'Credentials']
    session:
      strategy: 'jwt'
      maxAge: 86400
  database:
    orm: 'Prisma'
    provider: 'PostgreSQL'
    dbUrlEnv: '.env.local'
    prismaSchema: 'prisma/schema.prisma'
  api:
    trpc:
      routerPath: 'packages/server/src/trpc/routers'
      adapter: 'http'
  testing:
    unit: 'Vitest with TS testing utilities'
    integration: 'Playwright for e2e'
    ci: 'GitHub Actions with lint, test, build'
  security:
    rules:
      - 'Never embed secrets in client code or repos'
      - 'Do not bypass NextAuth middleware or bypass server-side auth checks'
      - 'Validate inputs and avoid unsafe eval'
  prohibited:
    - 'Do not import server-only modules in client code'
    - 'Do not rely on client-side DB writes for persistence'
  notes: 'Copy this into project root as .cursorrules. It will guide code generation and policy checks for Cursor AI.'

Recommended Project Structure

apps/
  web/                  # Next.js app (T3 stack)
    app/                # App Router entry
    src/
    prisma/             # Prisma client usage, migrations
packages/
  server/               # TRPC backend, middleware, routers
  db/                   # Prisma schema, migrations, seeders
  ui/                   # Shared React components
prisma/
  schema.prisma           # Prisma schema for Postgres
.env.local               # Local environment vars (DB URL, secrets)

Core Engineering Principles

• Type-safety first: end-to-end types across TRPC and Prisma.
• Secure by default: authenticate every API path and protect sessions.
• Declarative architecture: clear boundaries between app/web, server, and db layers.
• Automate testing and linting in CI to prevent regressions.
• Small, composable units: small TRPC routers with strict input validation.

Code Construction Rules

• Use Next.js App Router structure under apps/web with TRPC and NextAuth integration.
• Define TRPC routers with input schemas validated by Zod; export type-safe clients.
• Prisma models should reflect domain entities with consistent naming conventions.
• NextAuth should use secure session strategy (jwt) and rotate tokens where applicable.
• Client components must not access DB directly; use TRPC procedures for all data access.
• All API endpoints should implement input validation, error handling, and proper CORS configuration.
• CI should run yarn lint, test, and type-check on push to any branch.
• Do not hardcode secrets; load via environment variables.

Security and Production Rules

• Enforce server-side authentication checks for all sensitive endpoints.
• Store secrets in environment variables and use a secret manager in production.
• Use HTTPS, secure cookies, and httpOnly cookies for NextAuth sessions.
• Enable CSRF protection for credentials-based sign-in flows.
• Audit dependencies for known vulnerabilities and pin versions in package.json.

Testing Checklist

• Unit tests for TRPC procedures with mocked Prisma clients.
• Integration tests for login flows with NextAuth and provider mocks.
• End-to-end tests for critical user journeys using Playwright.
• Lint and type-check in CI; fail on warnings treated as errors.
• Static analysis for security: no secrets in repo, constrained permissions.

Common Mistakes to Avoid

• Relying on client-side DB mutations to drive server state.
• Skipping input validation in TRPC routers.
• Neglecting JWT session security: insecure cookies or improper token rotation.
• Ignoring environment-based configuration across dev/stage/prod.

FAQ

What is this Cursor Rules Template for Next.js T3 Stack?

This Cursor Rules Template provides a concrete set of Cursor AI instructions tailored for a Next.js 13+ application using the T3 stack (TRPC, Prisma, NextAuth). It defines project structure, security practices, and testing workflows so developers can drop the configuration into their repo and start coding with consistent AI guidance.

How do I use the included .cursorrules block?

Copy the entire code block above into a new file named .cursorrules at your repository root and reference it in Cursor AI tooling. The rules guide architecture, authentication, ORM usage, and testing; adjust environment-specific values as needed without changing core constraints.

What security practices are enforced by these rules?

The rules enforce NextAuth JWT sessions, server-side authentication checks, secret management, and avoidance of secrets in client code. They also require input validation and restricted API exposure, reducing surface area for attacks in a Next.js + TRPC + Prisma setup.

Can I extend this template for custom providers or domains?

Yes. The template defines providers (Google, GitHub, Credentials) and a standard TRPC scaffold. Extend with additional providers and domain-specific routers, but keep the validation, type-safety, and security constraints intact.

How do I test this stack in CI?

Run unit tests with Vitest, integration tests with Playwright, and dedicated lint/type-check jobs. Ensure the Prisma client is properly generated and migrations are applied in staging before deploying.