# T3 Stack (Next.js + tRPC + Prisma)

> Full-stack TypeScript application with tRPC, Prisma, and NextAuth.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: nextjs, postgresql, redis, nginx
- Tags: t3-stack, nextjs, trpc, prisma, typescript
- Source: https://docker.recipes/full-stacks/t3-stack-prisma

## Overview

Next.js is a React framework for building production-ready web applications with server-side rendering, static site generation, and full-stack capabilities. Developed by Vercel and first released in 2016, Next.js has become the de facto standard for React applications requiring SEO optimization, fast initial page loads, and developer productivity. It provides file-based routing, automatic code splitting, and built-in optimization features that eliminate the need for complex webpack configurations. The T3 Stack combines Next.js with tRPC (TypeScript Remote Procedure Call), Prisma ORM, and NextAuth for authentication, creating an end-to-end type-safe development experience. This stack leverages PostgreSQL for reliable data persistence with ACID compliance, Redis for high-performance session storage and caching, and NGINX for production-grade reverse proxying and static asset serving. The combination delivers sub-millisecond cache responses through Redis while maintaining complex relational data integrity with PostgreSQL. Organizations choose this stack for its complete TypeScript integration from database schema to frontend components, eliminating runtime type errors and improving developer productivity. Startups building SaaS platforms, e-commerce sites, and content management systems benefit from the rapid development cycle, while enterprises appreciate the type safety, scalability through PostgreSQL's table partitioning, and NGINX's proven ability to handle high-traffic loads with minimal resource consumption.

## Features

- End-to-end type safety from Prisma database schema through tRPC API routes to Next.js frontend components
- Server-side rendering and static site generation with automatic code splitting and image optimization
- tRPC client-server communication with automatic TypeScript inference and runtime validation
- NextAuth integration supporting OAuth providers like Discord, GitHub, and Google with session management
- Prisma ORM with database migrations, relation management, and automatic TypeScript client generation
- PostgreSQL JSONB support for flexible document storage alongside traditional relational data
- Redis-based session persistence with sub-millisecond response times for user authentication
- NGINX reverse proxy with HTTP/2 support, SSL termination, and static asset caching

## Use cases

- SaaS platforms requiring user authentication, subscription management, and complex business logic
- E-commerce applications with product catalogs, user accounts, and real-time inventory management
- Content management systems with author permissions, publishing workflows, and SEO optimization
- Social platforms with user profiles, real-time messaging, and activity feeds
- Internal business dashboards with role-based access control and data visualization
- API-first applications serving both web and mobile clients with type-safe endpoints
- Multi-tenant applications requiring data isolation and user-specific customizations

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for PostgreSQL and Redis
- Node.js knowledge and familiarity with React components and TypeScript syntax
- Basic understanding of SQL queries and relational database concepts for Prisma usage
- OAuth application credentials from Discord or other providers for NextAuth configuration
- Available ports 80, 443, 3000, and 5432 for NGINX, Next.js, and PostgreSQL services
- SSL certificates for production HTTPS setup through NGINX reverse proxy

## docker-compose.yml

```yaml
services:
  t3-app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXTAUTH_URL: http://localhost:3000
      DISCORD_CLIENT_ID: ${DISCORD_CLIENT_ID}
      DISCORD_CLIENT_SECRET: ${DISCORD_CLIENT_SECRET}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - t3-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - t3-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - t3-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - t3-app
    networks:
      - t3-net
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

networks:
  t3-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=t3app
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=t3app

# NextAuth
NEXTAUTH_SECRET=$(openssl rand -base64 32)

# Discord OAuth (optional)
DISCORD_CLIENT_ID=
DISCORD_CLIENT_SECRET=
```

## Usage notes

- Create T3 app: npm create t3-app@latest
- T3 App at http://localhost:3000
- Run Prisma migrations: npx prisma migrate deploy
- Type-safe API with tRPC

## Troubleshooting

- NextAuth NEXTAUTH_URL must match your domain exactly, including protocol and port for callback URLs to work
- Prisma migrate deploy fails: Ensure PostgreSQL health check passes and DATABASE_URL connection string is correct
- tRPC query fails with network error: Check that t3-app service can reach postgres and redis containers on t3-net network
- NGINX 502 Bad Gateway: Verify t3-app service is running on port 3000 and nginx.conf upstream configuration points to correct container name
- Redis connection refused: Confirm redis service started successfully and Next.js Redis client uses 'redis:6379' as connection string
- Build context errors: Ensure Dockerfile and package.json exist in current directory when running docker-compose up

