Home

Build a User Management App with Next.js

This tutorial demonstrates how to build a basic user management app. The app authenticates and identifies the user, stores their profile information in the database, and allows the user to log in, update their profile details, and upload a profile photo. The app uses:

  • Supabase Database - a Postgres database for storing your user data and Row Level Security so data is protected and users can only access their own information.
  • Supabase Auth - users log in through magic links sent to their email (without having to set up passwords).
  • Supabase Storage - users can upload a profile photo.

Supabase User Management example

note

If you get stuck while working through this guide, refer to the full example on GitHub.

Project setup#

Before we start building we're going to set up our Database and API. This is as simple as starting a new Project in Supabase and then creating a "schema" inside the database.

Create a project#

  1. Create a new project in the Supabase Dashboard.
  2. Enter your project details.
  3. Wait for the new database to launch.

Set up the database schema#

Now we are going to set up the database schema. We can use the "User Management Starter" quickstart in the SQL Editor, or you can just copy/paste the SQL from below and run it yourself.

  1. Go to the SQL Editor page in the Dashboard.
  2. Click User Management Starter.
  3. Click Run.

note

You can easily pull the database schema down to your local project by running the db pull command. Read the local development docs for detailed instructions.


_10
supabase link --project-ref <project-id>
_10
# You can get <project-id> from your project's dashboard URL: https://supabase.com/dashboard/project/<project-id>
_10
supabase db pull

Get the API Keys#

Now that you've created some database tables, you are ready to insert data using the auto-generated API. We just need to get the Project URL and anon key from the API settings.

  1. Go to the API Settings page in the Dashboard.
  2. Find your Project URL, anon, and service_role keys on this page.

Building the App#

Let's start building the Next.js app from scratch.

Initialize a Next.js app#

We can use create-next-app to initialize an app called supabase-nextjs:


_10
npx create-next-app@latest --use-npm supabase-nextjs
_10
cd supabase-nextjs

Then install the Supabase client library: supabase-js


_10
npm install @supabase/supabase-js

And finally we want to save the environment variables in a .env.local. All we need are the API URL and the anon key that you copied earlier.

.env.local

_10
NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
_10
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY

And one optional step is to update the CSS file app/globals.css to make the app look nice. You can find the full contents of this file here.

Supabase Auth Helpers#

Next.js is a highly versatile framework offering pre-rendering at build time (SSG), server-side rendering at request time (SSR), API routes, and middleware edge-functions.

It can be challenging to authenticate your users in all these different environments, that's why we've created the Supabase Auth Helpers to make user management and data fetching within Next.js as easy as possible.

Install the auth helpers for Next.js


_10
npm install @supabase/auth-helpers-nextjs @supabase/supabase-js

Next.js Middleware#

Create a middleware.js file and include the following content to:

  • Verify if there is an authenticated Supabase user
  • Validate if the user is authenticated and currently on the sign-in page, redirecting them to the account page
  • Verify if the user is not authenticated and currently on the account page, redirecting them to the sign-in page.
middleware.js

_27
import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs'
_27
import { NextResponse } from 'next/server'
_27
_27
export async function middleware(req) {
_27
const res = NextResponse.next()
_27
const supabase = createMiddlewareClient({ req, res })
_27
_27
const {
_27
data: { user },
_27
} = await supabase.auth.getUser()
_27
_27
// if user is signed in and the current path is / redirect the user to /account
_27
if (user && req.nextUrl.pathname === '/') {
_27
return NextResponse.redirect(new URL('/account', req.url))
_27
}
_27
_27
// if user is not signed in and the current path is not / redirect the user to /
_27
if (!user && req.nextUrl.pathname !== '/') {
_27
return NextResponse.redirect(new URL('/', req.url))
_27
}
_27
_27
return res
_27
}
_27
_27
export const config = {
_27
matcher: ['/', '/account'],
_27
}

Set up a Login component#

Supabase Auth UI#

We can use the Supabase Auth UI a pre-built React component for authenticating users via OAuth, email, and magic links.

Install the Supabase Auth UI for React


_10
npm install @supabase/auth-ui-react @supabase/auth-ui-shared

Create an AuthForm client side component with the Auth component rendered within it:

app/auth-form.jsx

_20
'use client'
_20
import { Auth } from '@supabase/auth-ui-react'
_20
import { ThemeSupa } from '@supabase/auth-ui-shared'
_20
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'
_20
_20
export default function AuthForm() {
_20
const supabase = createClientComponentClient()
_20
_20
return (
_20
<Auth
_20
supabaseClient={supabase}
_20
view="magic_link"
_20
appearance={{ theme: ThemeSupa }}
_20
theme="dark"
_20
showLinks={false}
_20
providers={[]}
_20
redirectTo="http://localhost:3000/auth/callback"
_20
/>
_20
)
_20
}

note

If you are using TypeScript for this project, see generating types to automatically generate types from your database tables.

Add the AuthForm component to your home page

app/page.js

_18
import AuthForm from './auth-form'
_18
_18
export default function Home() {
_18
return (
_18
<div className="row">
_18
<div className="col-6">
_18
<h1 className="header">Supabase Auth + Storage</h1>
_18
<p className="">
_18
Experience our Auth and Storage through a simple profile management example. Create a user
_18
profile and upload an avatar image. Fast, simple, secure.
_18
</p>
_18
</div>
_18
<div className="col-6 auth-widget">
_18
<AuthForm />
_18
</div>
_18
</div>
_18
)
_18
}

Proof Key for Code Exchange (PKCE)#

As we are employing Proof Key for Code Exchange (PKCE) in our authentication flow, it is necessary to create a route handler responsible for exchanging the code for a session.

In the following code snippet, we perform the following steps:

  • Retrieve the code sent back from the Supabase Auth server using the code query parameter.
  • Exchange this code for a session, which we store in our chosen storage mechanism (in this case, cookies).
  • Finally, we redirect the user to the account page.
app/auth/callback/route.js

_16
import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs'
_16
import { cookies } from 'next/headers'
_16
import { NextResponse } from 'next/server'
_16
_16
export async function GET(req) {
_16
const cookieStore = cookies()
_16
const supabase = createRouteHandlerClient({ cookies: () => cookieStore })
_16
const { searchParams } = new URL(req.url)
_16
const code = searchParams.get('code')
_16
_16
if (code) {
_16
await supabase.auth.exchangeCodeForSession(code)
_16
}
_16
_16
return NextResponse.redirect(new URL('/account', req.url))
_16
}

Sign out#

Let's create a route handler to handle the signout from the server side.

app/auth/signout/route.js

_21
import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs'
_21
import { cookies } from 'next/headers'
_21
import { NextResponse } from 'next/server'
_21
_21
export async function POST(req) {
_21
const cookieStore = cookies()
_21
const supabase = createRouteHandlerClient({ cookies: () => cookieStore })
_21
_21
// Check if we have a session
_21
const {
_21
data: { session },
_21
} = await supabase.auth.getSession()
_21
_21
if (session) {
_21
await supabase.auth.signOut()
_21
}
_21
_21
return NextResponse.redirect(new URL('/', req.url), {
_21
status: 302,
_21
})
_21
}

Account page#

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called AccountForm within the app/account folder.

app/account/account-form.jsx

_119
'use client'
_119
import { useCallback, useEffect, useState } from 'react'
_119
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'
_119
_119
export default function AccountForm({ session }) {
_119
const supabase = createClientComponentClient()
_119
const [loading, setLoading] = useState(true)
_119
const [fullname, setFullname] = useState(null)
_119
const [username, setUsername] = useState(null)
_119
const [website, setWebsite] = useState(null)
_119
const [avatar_url, setAvatarUrl] = useState(null)
_119
const user = session?.user
_119
_119
const getProfile = useCallback(async () => {
_119
try {
_119
setLoading(true)
_119
_119
const { data, error, status } = await supabase
_119
.from('profiles')
_119
.select(`full_name, username, website, avatar_url`)
_119
.eq('id', user?.id)
_119
.single()
_119
_119
if (error && status !== 406) {
_119
throw error
_119
}
_119
_119
if (data) {
_119
setFullname(data.full_name)
_119
setUsername(data.username)
_119
setWebsite(data.website)
_119
setAvatarUrl(data.avatar_url)
_119
}
_119
} catch (error) {
_119
alert('Error loading user data!')
_119
} finally {
_119
setLoading(false)
_119
}
_119
}, [user, supabase])
_119
_119
useEffect(() => {
_119
getProfile()
_119
}, [user, getProfile])
_119
_119
async function updateProfile({ username, website, avatar_url }) {
_119
try {
_119
setLoading(true)
_119
_119
const { error } = await supabase.from('profiles').upsert({
_119
id: user?.id,
_119
full_name: fullname,
_119
username,
_119
website,
_119
avatar_url,
_119
updated_at: new Date().toISOString(),
_119
})
_119
if (error) throw error
_119
alert('Profile updated!')
_119
} catch (error) {
_119
alert('Error updating the data!')
_119
} finally {
_119
setLoading(false)
_119
}
_119
}
_119
_119
return (
_119
<div className="form-widget">
_119
<div>
_119
<label htmlFor="email">Email</label>
_119
<input id="email" type="text" value={session?.user.email} disabled />
_119
</div>
_119
<div>
_119
<label htmlFor="fullName">Full Name</label>
_119
<input
_119
id="fullName"
_119
type="text"
_119
value={fullname || ''}
_119
onChange={(e) => setFullname(e.target.value)}
_119
/>
_119
</div>
_119
<div>
_119
<label htmlFor="username">Username</label>
_119
<input
_119
id="username"
_119
type="text"
_119
value={username || ''}
_119
onChange={(e) => setUsername(e.target.value)}
_119
/>
_119
</div>
_119
<div>
_119
<label htmlFor="website">Website</label>
_119
<input
_119
id="website"
_119
type="url"
_119
value={website || ''}
_119
onChange={(e) => setWebsite(e.target.value)}
_119
/>
_119
</div>
_119
_119
<div>
_119
<button
_119
className="button primary block"
_119
onClick={() => updateProfile({ fullname, username, website, avatar_url })}
_119
disabled={loading}
_119
>
_119
{loading ? 'Loading ...' : 'Update'}
_119
</button>
_119
</div>
_119
_119
<div>
_119
<form action="/auth/signout" method="post">
_119
<button className="button block" type="submit">
_119
Sign out
_119
</button>
_119
</form>
_119
</div>
_119
</div>
_119
)
_119
}

Create a account page for the AccountForm component we just created

app/account/page.jsx

_14
import { createServerComponentClient } from '@supabase/auth-helpers-nextjs'
_14
import { cookies } from 'next/headers'
_14
import AccountForm from './account-form'
_14
_14
export default async function Account() {
_14
const cookieStore = cookies()
_14
const supabase = createServerComponentClient({ cookies: () => cookieStore })
_14
_14
const {
_14
data: { session },
_14
} = await supabase.auth.getSession()
_14
_14
return <AccountForm session={session} />
_14
}

Launch!#

Now that we have all the pages, route handlers and components in place, let's run this in a terminal window:


_10
npm run dev

And then open the browser to localhost:3000 and you should see the completed app.

Bonus: Profile photos#

Every Supabase project is configured with Storage for managing large files like photos and videos.

Create an upload widget#

Let's create an avatar widget for the user so that they can upload a profile photo. We can start by creating a new component:

app/account/avatar.jsx

_87
'use client'
_87
import React, { useEffect, useState } from 'react'
_87
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'
_87
import Image from 'next/image'
_87
_87
export default function Avatar({ uid, url, size, onUpload }) {
_87
const supabase = createClientComponentClient()
_87
const [avatarUrl, setAvatarUrl] = useState(null)
_87
const [uploading, setUploading] = useState(false)
_87
_87
useEffect(() => {
_87
async function downloadImage(path) {
_87
try {
_87
const { data, error } = await supabase.storage.from('avatars').download(path)
_87
if (error) {
_87
throw error
_87
}
_87
_87
const url = URL.createObjectURL(data)
_87
setAvatarUrl(url)
_87
} catch (error) {
_87
console.log('Error downloading image: ', error)
_87
}
_87
}
_87
_87
if (url) downloadImage(url)
_87
}, [url, supabase])
_87
_87
const uploadAvatar = async (event) => {
_87
try {
_87
setUploading(true)
_87
_87
if (!event.target.files || event.target.files.length === 0) {
_87
throw new Error('You must select an image to upload.')
_87
}
_87
_87
const file = event.target.files[0]
_87
const fileExt = file.name.split('.').pop()
_87
const filePath = `${uid}-${Math.random()}.${fileExt}`
_87
_87
const { error: uploadError } = await supabase.storage.from('avatars').upload(filePath, file)
_87
_87
if (uploadError) {
_87
throw uploadError
_87
}
_87
_87
onUpload(filePath)
_87
} catch (error) {
_87
alert('Error uploading avatar!')
_87
} finally {
_87
setUploading(false)
_87
}
_87
}
_87
_87
return (
_87
<div>
_87
{avatarUrl ? (
_87
<Image
_87
width={size}
_87
height={size}
_87
src={avatarUrl}
_87
alt="Avatar"
_87
className="avatar image"
_87
style={{ height: size, width: size }}
_87
/>
_87
) : (
_87
<div className="avatar no-image" style={{ height: size, width: size }} />
_87
)}
_87
<div style={{ width: size }}>
_87
<label className="button primary block" htmlFor="single">
_87
{uploading ? 'Uploading ...' : 'Upload'}
_87
</label>
_87
<input
_87
style={{
_87
visibility: 'hidden',
_87
position: 'absolute',
_87
}}
_87
type="file"
_87
id="single"
_87
accept="image/*"
_87
onChange={uploadAvatar}
_87
disabled={uploading}
_87
/>
_87
</div>
_87
</div>
_87
)
_87
}

Add the new widget#

And then we can add the widget to the AccountForm component:

app/account/account-form.js

_20
// Import the new component
_20
import Avatar from './avatar'
_20
_20
// ...
_20
_20
return (
_20
<div className="form-widget">
_20
{/* Add to the body */}
_20
<Avatar
_20
uid={user.id}
_20
url={avatar_url}
_20
size={150}
_20
onUpload={(url) => {
_20
setAvatarUrl(url)
_20
updateProfile({ fullname, username, website, avatar_url: url })
_20
}}
_20
/>
_20
{/* ... */}
_20
</div>
_20
)

Storage management#

If you upload additional profile photos, they'll accumulate in the avatars bucket because of their random names with only the latest being referenced from public.profiles and the older versions getting orphaned.

To automatically remove obsolete storage objects, extend the database triggers. Note that it is not sufficient to delete the objects from the storage.objects table because that would orphan and leak the actual storage objects in the S3 backend. Instead, invoke the storage API within Postgres via the http extension.

Enable the http extension for the extensions schema in the Dashboard. Then, define the following SQL functions in the SQL Editor to delete storage objects via the API:


_34
create or replace function delete_storage_object(bucket text, object text, out status int, out content text)
_34
returns record
_34
language 'plpgsql'
_34
security definer
_34
as $$
_34
declare
_34
project_url text := '<YOURPROJECTURL>';
_34
service_role_key text := '<YOURSERVICEROLEKEY>'; -- full access needed
_34
url text := project_url||'/storage/v1/object/'||bucket||'/'||object;
_34
begin
_34
select
_34
into status, content
_34
result.status::int, result.content::text
_34
FROM extensions.http((
_34
'DELETE',
_34
url,
_34
ARRAY[extensions.http_header('authorization','Bearer '||service_role_key)],
_34
NULL,
_34
NULL)::extensions.http_request) as result;
_34
end;
_34
$$;
_34
_34
create or replace function delete_avatar(avatar_url text, out status int, out content text)
_34
returns record
_34
language 'plpgsql'
_34
security definer
_34
as $$
_34
begin
_34
select
_34
into status, content
_34
result.status, result.content
_34
from public.delete_storage_object('avatars', avatar_url) as result;
_34
end;
_34
$$;

Next, add a trigger that removes any obsolete avatar whenever the profile is updated or deleted:


_32
create or replace function delete_old_avatar()
_32
returns trigger
_32
language 'plpgsql'
_32
security definer
_32
as $$
_32
declare
_32
status int;
_32
content text;
_32
avatar_name text;
_32
begin
_32
if coalesce(old.avatar_url, '') <> ''
_32
and (tg_op = 'DELETE' or (old.avatar_url <> new.avatar_url)) then
_32
-- extract avatar name
_32
avatar_name := old.avatar_url;
_32
select
_32
into status, content
_32
result.status, result.content
_32
from public.delete_avatar(avatar_name) as result;
_32
if status <> 200 then
_32
raise warning 'Could not delete avatar: % %', status, content;
_32
end if;
_32
end if;
_32
if tg_op = 'DELETE' then
_32
return old;
_32
end if;
_32
return new;
_32
end;
_32
$$;
_32
_32
create trigger before_profile_changes
_32
before update of avatar_url or delete on public.profiles
_32
for each row execute function public.delete_old_avatar();

Finally, delete the public.profile row before a user is deleted. If this step is omitted, you won't be able to delete users without first manually deleting their avatar image.


_14
create or replace function delete_old_profile()
_14
returns trigger
_14
language 'plpgsql'
_14
security definer
_14
as $$
_14
begin
_14
delete from public.profiles where id = old.id;
_14
return old;
_14
end;
_14
$$;
_14
_14
create trigger before_delete_user
_14
before delete on auth.users
_14
for each row execute function public.delete_old_profile();

At this stage you have a fully functional application!

See also#