supabase-realtime-chat-template

A lightweight chat application demonstrating Supabase Realtime for instant message updates, user authentication with RLS, and presence tracking. Built with React/Next.js, this starter is designed to be easy to extend—add rooms, threads, reactions, or even turn it into a live support system.

Features

• 🔐 Authentication - Email/password authentication with Supabase Auth
• 💬 Real-time Messaging - Instant message updates using Supabase Realtime subscriptions
• 👥 Presence Tracking - See who's online in real-time
• 🔒 Row Level Security (RLS) - Secure data access with PostgreSQL policies
• 🎨 Modern UI - Clean, responsive design with Tailwind CSS and dark mode support
• ⚡ Next.js 14 - Built with App Router and Server Components
• 📱 Responsive - Works seamlessly on desktop and mobile devices

Prerequisites

• Node.js 18+ and npm/yarn/pnpm
• A Supabase account (sign up for free)

Getting Started

1. Clone the repository

git clone <your-repo-url>
cd supabase-realtime-chat-template

2. Install dependencies

npm install
# or
yarn install
# or
pnpm install

3. Set up Supabase

1. Create a new project at supabase.com
2. Go to your project's SQL Editor
3. Run the migration file supabase/migrations/001_initial_schema.sql to create the necessary tables and policies

4. Configure environment variables

1. Copy .env.local.example to .env.local:

   cp .env.local.example .env.local

2. Get your Supabase credentials:

   • Go to your Supabase project settings
   • Navigate to API settings
   • Copy your Project URL and anon public key

3. Update .env.local with your credentials:

   NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

5. Run the development server

npm run dev
# or
yarn dev
# or
pnpm dev

Open http://localhost:3000 in your browser.

6. Create your first account

• Navigate to /auth (or you'll be redirected automatically)
• Sign up with your email and password
• Start chatting!

Project Structure

├── app/
│   ├── auth/
│   │   └── page.tsx          # Authentication page
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Main chat page
├── components/
│   ├── AuthForm.tsx           # Sign in/sign up form
│   ├── Chat.tsx               # Main chat component
│   ├── MessageList.tsx        # Message display component
│   ├── MessageInput.tsx       # Message input component
│   └── UserList.tsx           # Online users sidebar
├── lib/
│   └── supabase/
│       ├── client.ts          # Browser Supabase client
│       ├── server.ts          # Server Supabase client
│       └── middleware.ts      # Middleware helper
├── supabase/
│   └── migrations/
│       └── 001_initial_schema.sql  # Database schema
└── middleware.ts              # Next.js middleware for auth

Database Schema

The application uses two main tables:

profiles

• Extends Supabase Auth users
• Stores username and avatar URL
• Automatically created when a user signs up

messages

• Stores chat messages
• Linked to users via user_id
• Includes content and timestamp
• Enabled for Realtime subscriptions

Both tables use Row Level Security (RLS) policies to ensure users can only modify their own data while allowing read access to all authenticated users.

How It Works

Real-time Messaging

Messages are synchronized in real-time using Supabase's Postgres Realtime feature:

1. When a user sends a message, it's inserted into the messages table
2. Supabase Realtime broadcasts the change to all subscribed clients
3. The Chat component listens for INSERT, UPDATE, and DELETE events
4. Messages are automatically added/updated/removed in the UI

Presence Tracking

User presence is tracked using Supabase Realtime Presence:

1. When a user joins, they track their presence in a dedicated channel
2. Other users receive presence updates (join/leave events)
3. The online users list updates automatically
4. Presence is cleaned up when users disconnect

Authentication Flow

1. Users sign up/sign in via the /auth page
2. Supabase Auth handles authentication
3. A profile is automatically created via database trigger
4. Middleware refreshes the session on each request
5. Protected routes redirect unauthenticated users

Extending the Template

This template is designed to be easily extended. Here are some ideas:

Add Chat Rooms

• Create a rooms table
• Add room_id to messages
• Filter messages by room
• Add room selection UI

Add Threads/Replies

• Add parent_message_id to messages
• Create nested message display
• Add reply functionality

Add Reactions

• Create a reactions table
• Add reaction buttons to messages
• Display reaction counts

Add File Uploads

• Use Supabase Storage
• Add file upload component
• Display images/files in messages

Turn into Support System

• Add ticket/thread management
• Add agent assignment
• Add status tracking
• Add priority levels

Technologies Used

• Next.js 14 - React framework with App Router
• TypeScript - Type-safe JavaScript
• Supabase - Backend as a service (Auth, Database, Realtime)
• Tailwind CSS - Utility-first CSS framework
• React - UI library

License

MIT

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.