User Management Tutorial

Learn how to build a user management system that allows users to sign up, sign in, and manage their profile information including avatar images.

What You’ll Build

A user management system with:

Email/password authentication
User profile management
Avatar image uploads
Public profile pages
Row Level Security for data protection

Architecture Overview

This application uses:

Supabase Auth for user authentication
Supabase Database for storing profile data
Supabase Storage for avatar images
Next.js App Router for the frontend

Create a New Project

Go to supabase.com/dashboard
Click New Project
Configure your project:
- Name: User Management App
- Database Password: Use a strong password
- Region: Choose your preferred region
Click Create new project

Run the User Management Quickstart

In the SQL Editor:

Navigate to SQL Editor
Find User Management Starter: Sets up a public Profiles table
Click Run

This creates the necessary database schema:

-- Create a table for public profiles
create table profiles (
  id uuid references auth.users on delete cascade not null primary key,
  updated_at timestamp with time zone,
  username text unique,
  full_name text,
  avatar_url text,
  website text,
  constraint username_length check (char_length(username) >= 3)
);

-- Set up Row Level Security (RLS)
alter table profiles enable row level security;

create policy "Public profiles are viewable by everyone." 
  on profiles for select 
  using (true);

create policy "Users can insert their own profile." 
  on profiles for insert 
  with check ((select auth.uid()) = id);

create policy "Users can update own profile." 
  on profiles for update 
  using ((select auth.uid()) = id);

-- Auto-create profile on user signup
create function public.handle_new_user()
returns trigger as $$
begin
  insert into public.profiles (id, full_name, avatar_url)
  values (new.id, new.raw_user_meta_data->>'full_name', new.raw_user_meta_data->>'avatar_url');
  return new;
end;
$$ language plpgsql security definer;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

-- Set up Storage
insert into storage.buckets (id, name)
  values ('avatars', 'avatars');

-- Storage policies
create policy "Avatar images are publicly accessible." 
  on storage.objects for select 
  using (bucket_id = 'avatars');

create policy "Anyone can upload an avatar." 
  on storage.objects for insert 
  with check (bucket_id = 'avatars');

create policy "Anyone can update their own avatar." 
  on storage.objects for update 
  using (auth.uid()::text = (storage.foldername(name))[1]);

Set Up Your Next.js App

Create a new Next.js application:

npx create-next-app@latest user-management
cd user-management

Install Supabase packages:

npm install @supabase/supabase-js @supabase/ssr

Create .env.local:

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

Create Supabase Client Utilities

Create lib/supabase/client.ts for client-side operations:

import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

Create lib/supabase/server.ts for server-side operations:

import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export async function createClient() {
  const cookieStore = await cookies()

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // Server Component - ignore
          }
        },
      },
    }
  )
}

Build the Avatar Component

Create app/account/avatar.tsx:

'use client'
import React, { useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'
import Image from 'next/image'

export default function Avatar({
  uid,
  url,
  size,
  onUpload,
}: {
  uid: string | null
  url: string | null
  size: number
  onUpload: (url: string) => void
}) {
  const supabase = createClient()
  const [avatarUrl, setAvatarUrl] = useState<string | null>(url)
  const [uploading, setUploading] = useState(false)

  useEffect(() => {
    async function downloadImage(path: string) {
      try {
        const { data, error } = await supabase.storage
          .from('avatars')
          .download(path)
        
        if (error) throw error
        
        const url = URL.createObjectURL(data)
        setAvatarUrl(url)
      } catch (error) {
        console.log('Error downloading image: ', error)
      }
    }

    if (url) downloadImage(url)
  }, [url, supabase])

  const uploadAvatar: React.ChangeEventHandler<HTMLInputElement> = async (event) => {
    try {
      setUploading(true)

      if (!event.target.files || event.target.files.length === 0) {
        throw new Error('You must select an image to upload.')
      }

      const file = event.target.files[0]
      const fileExt = file.name.split('.').pop()
      const filePath = `${uid}-${Math.random()}.${fileExt}`

      const { error: uploadError } = await supabase.storage
        .from('avatars')
        .upload(filePath, file)

      if (uploadError) throw uploadError

      onUpload(filePath)
    } catch (error) {
      alert('Error uploading avatar!')
    } finally {
      setUploading(false)
    }
  }

  return (
    <div className="flex flex-col items-center gap-4">
      {avatarUrl ? (
        <Image
          width={size}
          height={size}
          src={avatarUrl}
          alt="Avatar"
          className="rounded-full"
        />
      ) : (
        <div 
          className="rounded-full bg-gray-200" 
          style={{ height: size, width: size }} 
        />
      )}
      <div>
        <label 
          className="px-4 py-2 bg-blue-500 text-white rounded cursor-pointer" 
          htmlFor="single"
        >
          {uploading ? 'Uploading ...' : 'Upload Avatar'}
        </label>
        <input
          className="hidden"
          type="file"
          id="single"
          accept="image/*"
          onChange={uploadAvatar}
          disabled={uploading}
        />
      </div>
    </div>
  )
}

Build the Account Form

Create app/account/account-form.tsx:

'use client'
import { useCallback, useEffect, useState } from 'react'
import { createClient } from '@/lib/supabase/client'
import { type User } from '@supabase/supabase-js'
import Avatar from './avatar'

export default function AccountForm({ user }: { user: User | null }) {
  const supabase = createClient()
  const [loading, setLoading] = useState(true)
  const [fullname, setFullname] = useState<string | null>(null)
  const [username, setUsername] = useState<string | null>(null)
  const [website, setWebsite] = useState<string | null>(null)
  const [avatar_url, setAvatarUrl] = useState<string | null>(null)

  const getProfile = useCallback(async () => {
    try {
      setLoading(true)

      const { data, error, status } = await supabase
        .from('profiles')
        .select(`full_name, username, website, avatar_url`)
        .eq('id', user?.id)
        .single()

      if (error && status !== 406) throw error

      if (data) {
        setFullname(data.full_name)
        setUsername(data.username)
        setWebsite(data.website)
        setAvatarUrl(data.avatar_url)
      }
    } catch (error) {
      alert('Error loading user data!')
    } finally {
      setLoading(false)
    }
  }, [user, supabase])

  useEffect(() => {
    getProfile()
  }, [user, getProfile])

  async function updateProfile({
    username,
    website,
    avatar_url,
  }: {
    username: string | null
    fullname: string | null
    website: string | null
    avatar_url: string | null
  }) {
    try {
      setLoading(true)

      const { error } = await supabase.from('profiles').upsert({
        id: user?.id as string,
        full_name: fullname,
        username,
        website,
        avatar_url,
        updated_at: new Date().toISOString(),
      })
      
      if (error) throw error
      alert('Profile updated!')
    } catch (error) {
      alert('Error updating the data!')
    } finally {
      setLoading(false)
    }
  }

  return (
    <div className="max-w-md mx-auto p-8 space-y-6">
      <Avatar
        uid={user?.id ?? null}
        url={avatar_url}
        size={150}
        onUpload={(url) => {
          setAvatarUrl(url)
          updateProfile({ fullname, username, website, avatar_url: url })
        }}
      />
      
      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          Email
        </label>
        <input 
          id="email" 
          type="text" 
          value={user?.email} 
          disabled 
          className="mt-1 block w-full rounded border p-2 bg-gray-100"
        />
      </div>
      
      <div>
        <label htmlFor="fullName" className="block text-sm font-medium">
          Full Name
        </label>
        <input
          id="fullName"
          type="text"
          value={fullname || ''}
          onChange={(e) => setFullname(e.target.value)}
          className="mt-1 block w-full rounded border p-2"
        />
      </div>
      
      <div>
        <label htmlFor="username" className="block text-sm font-medium">
          Username
        </label>
        <input
          id="username"
          type="text"
          value={username || ''}
          onChange={(e) => setUsername(e.target.value)}
          className="mt-1 block w-full rounded border p-2"
        />
      </div>
      
      <div>
        <label htmlFor="website" className="block text-sm font-medium">
          Website
        </label>
        <input
          id="website"
          type="url"
          value={website || ''}
          onChange={(e) => setWebsite(e.target.value)}
          className="mt-1 block w-full rounded border p-2"
        />
      </div>

      <div className="space-y-2">
        <button
          className="w-full px-4 py-2 bg-blue-500 text-white rounded"
          onClick={() => updateProfile({ fullname, username, website, avatar_url })}
          disabled={loading}
        >
          {loading ? 'Loading ...' : 'Update Profile'}
        </button>

        <form action="/auth/signout" method="post">
          <button className="w-full px-4 py-2 bg-gray-200 rounded" type="submit">
            Sign Out
          </button>
        </form>
      </div>
    </div>
  )
}

Create the Account Page

Create app/account/page.tsx:

import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import AccountForm from './account-form'

export default async function Account() {
  const supabase = await createClient()

  const {
    data: { user },
  } = await supabase.auth.getUser()

  if (!user) {
    return redirect('/login')
  }

  return <AccountForm user={user} />
}

Create the Login Page

Create app/login/page.tsx:

import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import { login, signup } from './actions'

export default async function LoginPage() {
  const supabase = await createClient()
  const { data } = await supabase.auth.getUser()

  if (data?.user) {
    redirect('/account')
  }

  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="max-w-md w-full p-8 bg-white rounded-lg shadow">
        <h1 className="text-2xl font-bold mb-6">Sign In</h1>
        <form className="space-y-4">
          <div>
            <label htmlFor="email" className="block text-sm font-medium">
              Email
            </label>
            <input
              id="email"
              name="email"
              type="email"
              required
              className="mt-1 block w-full rounded border p-2"
            />
          </div>
          
          <div>
            <label htmlFor="password" className="block text-sm font-medium">
              Password
            </label>
            <input
              id="password"
              name="password"
              type="password"
              required
              className="mt-1 block w-full rounded border p-2"
            />
          </div>
          
          <div className="flex gap-2">
            <button 
              formAction={login}
              className="flex-1 px-4 py-2 bg-blue-500 text-white rounded"
            >
              Sign In
            </button>
            <button 
              formAction={signup}
              className="flex-1 px-4 py-2 bg-gray-200 rounded"
            >
              Sign Up
            </button>
          </div>
        </form>
      </div>
    </div>
  )
}

Create app/login/actions.ts:

'use server'

import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'

export async function login(formData: FormData) {
  const supabase = await createClient()

  const data = {
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  }

  const { error } = await supabase.auth.signInWithPassword(data)

  if (error) {
    redirect('/error')
  }

  revalidatePath('/', 'layout')
  redirect('/account')
}

export async function signup(formData: FormData) {
  const supabase = await createClient()

  const data = {
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  }

  const { error } = await supabase.auth.signUp(data)

  if (error) {
    redirect('/error')
  }

  revalidatePath('/', 'layout')
  redirect('/account')
}

Test Your Application

Run the development server:

npm run dev

Visit http://localhost:3000/login:

Create a new account
Fill in your profile information
Upload an avatar image
Update your profile

Key Concepts

Row Level Security

RLS policies ensure:

Anyone can view profiles (select using (true))
Users can only update their own profile
Profiles are automatically created on signup via trigger

Storage Policies

Storage policies control:

Public read access to avatars
Authenticated users can upload
Users can only update their own avatars

Server vs Client Components

Next.js App Router pattern:

Server Components: Fetch user data securely
Client Components: Handle interactivity (forms, uploads)

Next Steps

Add Social Auth

Enable Google, GitHub, and other OAuth providers

File Upload Tutorial

Learn advanced storage techniques

Realtime Presence

Show online users in real-time

Example Code

Explore more authentication examples

Tutorials

Integration Guides

Examples

User Management Tutorial

What You’ll Build

Architecture Overview

Key Concepts

Row Level Security

Storage Policies

Server vs Client Components

Next Steps

Add Social Auth

File Upload Tutorial

Realtime Presence

Example Code

Tutorials

Integration Guides

Examples

​What You’ll Build

​Architecture Overview

​Key Concepts

​Row Level Security

​Storage Policies

​Server vs Client Components

​Next Steps

Add Social Auth

File Upload Tutorial

Realtime Presence

Example Code

What You’ll Build

Architecture Overview

Key Concepts

Row Level Security

Storage Policies

Server vs Client Components

Next Steps