Home

Build a User Management App with NextJS

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.

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

NextJS 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

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

Sign out#

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

app/auth/signout/route.js

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

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

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

Create a account page for the AccountForm component we just created

app/account/page.jsx

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

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
let { 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:


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