Next.js 16 frontend application with authentication, database integration, and modern UI

Web Application

The Web application is a modern, responsive Next.js 16 frontend built with TypeScript, shadcn/ui, and Tailwind CSS. It integrates with the API, authentication, and database packages for a complete user experience.

Overview

Framework: Next.js 16 with TypeScript
Location: apps/web
UI Library: shadcn/ui with Tailwind CSS
Authentication: Better Auth with Google OAuth and two-factor support
Database: PostgreSQL via Prisma (shared db package)
Port: http://localhost:3000

Architecture

The Web app uses shared packages from the monorepo:

@workspace/auth - Session management, OAuth, and authentication flows
@workspace/db - Prisma ORM and database client
@workspace/ui - Reusable React components and design system
@workspace/email - Email templates for notifications
@workspace/utils - Shared utilities and type definitions
@workspace/vitest-presets - Shared Vitest configuration for web testing

Features

Design System

shadcn/ui Components - High-quality, accessible React components
Tailwind CSS - Utility-first styling with responsive design
Dark Mode Support - Built-in light/dark mode using shadcn/ui themes
Responsive Layout - Mobile-first design that works on all screen sizes

Authentication

Session Management - Secure session handling with Better Auth
Google OAuth - Sign in with Google account
Two-Factor Authentication - Additional security layer for user accounts
Protected Routes - Middleware ensures authenticated access

SEO & Performance

Server-Side Rendering - SSR for better performance and SEO
Meta Tags - Automatic generation of Open Graph and Twitter Card tags
Image Optimization - Next.js Image component for responsive images
Static Generation - ISR (Incremental Static Regeneration) for frequently accessed pages

Project Structure

apps/web/
├── app/                  # Next.js app directory
│   ├── layout.tsx        # Root layout with providers
│   ├── page.tsx          # Home page
│   ├── (auth)/           # Authentication routes
│   │   ├── signin/
│   │   ├── signup/
│   │   └── ...
│   ├── (dashboard)/      # Protected dashboard routes
│   │   ├── page.tsx
│   │   ├── profile/
│   │   └── settings/
│   └── api/              # API route handlers
├── components/           # React components
│   ├── ui/               # shadcn/ui components
│   ├── forms/            # Form components
│   └── layout/           # Layout components
├── lib/                  # Utility functions
├── hooks/                # Custom React hooks
├── types/                # TypeScript type definitions
├── public/               # Static assets
├── .env.example          # Environment variables template
├── next.config.ts        # Next.js configuration
├── tsconfig.json         # TypeScript configuration
└── package.json          # Dependencies and scripts

Environment Variables

For detailed environment variable setup and configuration, see the Environment Variables Guide.

Copy .env.example to .env.local and fill in the required values following the configuration guide.

Setup & Installation

Follow the Getting Started Guide for complete setup instructions.

Quick summary for the web app:

# 1. Install dependencies
pnpm install

# 2. Configure environment variables
cp .env.example .env.local

# 3. Set up database
pnpm db:generate && pnpm db:migrate

# 4. Start development server
pnpm dev

Visit http://localhost:3000 to see the application.

The development server includes hot reload, so changes to your code are reflected instantly.

Key Scripts

Command	Purpose
`pnpm dev`	Start development server with hot reload
`pnpm build`	Build for production
`pnpm start`	Start production server
`pnpm lint`	Check code quality with ESLint
`pnpm lint:fix`	Auto-fix ESLint issues
`pnpm check-types`	Check TypeScript types
`pnpm test`	Run Vitest test suite
`pnpm test:watch`	Run tests in watch mode
`pnpm test:coverage`	Generate test coverage report

See Development Workflow for more commands and options.

Key Files

File	Purpose
`app/layout.tsx`	Root layout with providers (auth, theme, etc.)
`app/(home)/page.tsx`	Home page
`proxy.ts`	Next.js proxy for authentication checks
`components`	All React components
`next.config.ts`	Next.js configuration (images, redirects, etc.)

Pages & Routes

Public Pages

Home (/) - Welcome page with project overview
Sign In (/sign-in) - User login
Sign Up (/sign-up) - User registration
Forgot Password (/forgot-password) - Password reset flow
Reset Password (/reset-password) - Set new password after reset request

Protected Pages (Requires Auth)

Dashboard (/dashboard) - User dashboard and overview
Profile (/profile) - User profile management
Settings (/settings) - Account and app settings
Auth Pages - Two-factor setup, session management, etc.

Development Tips

Hot Reload

Code changes automatically reload in the browser during development - no manual refresh needed.

Database Changes

After modifying schema.prisma, run:

pnpm db:generate
pnpm db:migrate

Component Development

Use the shadcn/ui component library for UI - all components are pre-configured and styled consistently.

API Integration

The app communicates with the API on http://localhost:4000 (configurable via NEXT_PUBLIC_API_URL).

Type Safety

Always use TypeScript types for database models and API responses - use @workspace/db for Prisma types.

Building for Production

# Build the application
pnpm build

# Start production server
pnpm start

# Or use Docker
docker-compose -f docker-compose.prod.yml up web

The build process:

Compiles TypeScript to JavaScript
Bundles dependencies
Optimizes images and static assets
Generates static pages where possible

Ensure all environment variables are set correctly in production before building.

Verify BETTER_AUTH_SECRET is set correctly
Check GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for OAuth
Ensure proxy.ts is protecting routes correctly
Clear browser cookies and try again

For shared authentication configuration, see Authentication Not Working in the main guide.

Build Fails

# Clear Next.js cache
rm -rf .next

# Rebuild
pnpm build

# Or check for TypeScript errors
pnpm check-types

Authentication Package - Session and OAuth setup
Database Package - Prisma schema and migrations
UI Components - Available components and usage
Vitest Presets - Shared test configuration
Environment Variables - Detailed config guide
Code Quality - Linting and formatting

For deployment information, see the Deployment Guide.

Web