osdev-auth-supabase-with-username

Complete Next.js authentication template with Supabase including custom username support for all auth providers.

A production-ready Next.js 14+ authentication template powered by Supabase with built-in username support for all authentication providers (email, OAuth, etc.).

✨ Features

• ✅ Custom Username System - Works with email and OAuth signups
• ✅ Automatic Profile Creation - Smart defaults for missing user data
• ✅ Unique Username Generation - Automatic conflict resolution
• ✅ All Auth Providers - Google, GitHub, and more
• ✅ Complete Auth Flows - Signup, login, password reset, email confirmation
• ✅ Modern UI - shadcn/ui components with dark/light theme
• ✅ TypeScript - Fully typed for better DX
• ✅ RLS Configured - Row Level Security ready
• ✅ Public Usernames - Perfect for @mentions and profiles

🚀 Quick Start

Using npx (Recommended)

npx osdev-auth-supabase-with-username my-app
cd my-app
npm install

Manual Installation

# Clone the repository
git clone https://github.com/omransoliman97/nextjs-supabase-auth-osdev-with-username.git my-app
cd my-app

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your Supabase credentials

# Run development server
npm run dev

📦 What's Included

Dependencies

All required dependencies will be installed:

• @supabase/supabase-js & @supabase/ssr - Supabase client
• shadcn/ui components - Alert, Button, Card, Input, Label, Sonner
• react-icons - Icon library
• next-themes - Dark/Light theme support
• tw-animate-css - Animation utilities
• TypeScript configuration

Project Structure

├── app/
│   ├── (auth)/
│   │   ├── login/              # Login page
│   │   ├── signup/             # Signup with username
│   │   ├── forgot-password/    # Password reset request
│   │   ├── reset-password/     # Update password
│   │   └── auth/
│   │       ├── callback/       # OAuth callback
│   │       ├── confirm/        # Email confirmation
│   │       └── confirmed/      # Success page
│   ├── error/                  # Error page
│   └── not-found/              # 404 page
├── components/
│   ├── LoginForm.tsx
│   ├── SignupForm.tsx
│   ├── RequestResetForm.tsx
│   ├── UpdatePasswordForm.tsx
│   ├── ProvidersButtons.tsx
│   └── ThemeToggle.tsx
├── lib/
│   ├── auth-functions.ts       # All auth operations
│   ├── auth-utils.ts           # Server-side utilities
│   └── auth-utils-client.ts    # Client-side utilities
├── hooks/
│   └── useAuthRedirectClient.ts # Client-side protection
├── utils/supabase/
│   ├── client.ts
│   ├── server.ts
│   └── middleware.ts
└── IMPORTANT/
    ├── INSTRUCTIONS.md         # Complete setup guide
    ├── DatabaseProfilesHandler.md
    ├── EmailConfirmSignUp.md
    ├── EmailResetPassword.md
    └── PublicCanViewUsername.md

🔧 Setup Requirements

Prerequisites

• Node.js 18.0 or higher
• Supabase account (Sign up here)
• Basic knowledge of Next.js and React

Environment Variables

NEXT_PUBLIC_BASE_URL=your-url
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Database Setup

The template includes SQL scripts for:

1. Creating the profiles table
2. handle_new_user function (auto-creates profiles)
3. Database trigger (runs on user signup)
4. RLS policies (public username access)

📖 See IMPORTANT/INSTRUCTIONS.md for complete setup guide.

🎯 How It Works

Username System

When a user signs up, data is stored in raw_user_meta_data:

{
  first_name: "Omran",
  last_name: "Soliman",
  username: "omransoliman"
}

The handle_new_user function automatically:

• Creates a profile with first_name, last_name, and username
• Applies smart defaults for missing data
• Generates unique usernames (e.g., omransoliman → omransoliman79 if duplicate)
• Works with ALL auth providers (email, Google, GitHub, etc.)

Public Usernames

Usernames are publicly accessible through RLS policies, perfect for:

• @mentions in social features
• Public user profiles
• User discovery
• Leaderboards and rankings

📚 Documentation

Comprehensive documentation included:

• INSTRUCTIONS.md - Complete setup guide with troubleshooting
• Database scripts - Ready-to-use SQL for Supabase
• Email templates - Customizable confirmation and reset emails
• Code comments - Every file is well-documented

🛠️ Commands

# Development
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint

🌐 Deploy

Vercel (Recommended)

1. Push your code to GitHub
2. Import to Vercel
3. Add environment variables
4. Deploy

📖 Next.js Deployment Docs

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Omran Soliman

🔗 Links

• GitHub Repository
• Report Issues
• Supabase Documentation
• Next.js Documentation

⭐ Support

If this template helped you, please give it a star on GitHub!

Perfect for: SaaS applications, social platforms, community sites, or any project requiring usernames with authentication.