@floatingpixels/supabase-nuxt is a Nuxt module for first class integration with Supabase. It makes it easy to use Supabase authentication, database and realtime features in your Nuxt 3 application. Especially when using server-side rendering SSR, using Supabase can be tricky, this module takes care of the intricacies and lets you simply use the power of Supabase!
Checkout the Nuxt 3 documentation and Supabase to learn more.
Add @floatingpixels/supabase-nuxt dev dependency to your project:
pnpm add -D @floatingpixels/supabase-nuxt
yarn add --dev @floatingpixels/supabase-nuxt
npm install @floatingpixels/supabase-nuxt --save-dev
bun add -D @floatingpixels/supabase-nuxtAdd @floatingpixels/supabase-nuxt to the modules section of nuxt.config.ts:
export default defineNuxtConfig({
modules: ['@floatingpixels/supabase-nuxt'],
})Add SUPABASE_URL and SUPABASE_ANON_KEY to .env:
NUXT_PUBLIC_SUPABASE_URL="https://example.supabase.co"
NUXT_PUBLIC_SUPABASE_ANON_KEY=""When dynamically setting the variables during in an environment, make sure to prefix the environment variables with NUXT_PUBLIC_ in order to use runtimeConfig.
The public keys are required to be set in the environment for the module to work. If the service role is needed, you should also set NUXT_SUPABASE_SERVICE_ROLE_KEY in the environment, which will be only available on the server side as a private runtime variable.
You can configure the Supabase module by using the supabase key in nuxt.config:
export default defineNuxtConfig({
// ...
supabase: {
// Options
}
}Default: process.env.NUXT_PUBLIC_SUPABASE_URL (e.g.: https://example.supabase.co)
The unique Supabase URL which is supplied when you create a new project in your project dashboard.
Default: process.env.NUXT_PUBLIC_SUPABASE_ANON_KEY
Supabase 'anon key', used to bypass the Supabase API gateway and interact with your Supabase database making use of user JWT to apply RLS Policies.
Default: process.env.NUXT_SUPABASE_SERVICE_ROLE_KEY
Supabase 'service role key', has super admin rights and can bypass your Row Level Security.
Default: false
Re-direct automatically to the configured login page if a non authenticated user is navigating to a page. When set to true a global middleware is used to check for a logged-in Supabase use on all non-excluded routes.
Default:
redirectOptions: {
login: '/login',
exclude: [],
}login: User will be redirected to this route if not authenticated or after logout.exclude: Routes to exclude from the re-direct.['/foo', '/bar/*']will exclude thefoopage and all pages in yourbarfolder.
Default:
clientOptions: {
auth: {
flowType: 'pkce',
detectSessionInUrl: true,
persistSession: true,
autoRefreshToken: true
},
}A documentation of Supabase client options is available here.
The module makes it easy to use Supabase Auth in your application. In most use-cases for Supabase you'll want users to be authenticated, so you can leverage row-level security (RLS) in the database. Supabase Auth is designed to work perfectly with RLS.
All you need to do is to create a login page, when using the default module settings that's login.vue in the pages folder. On the log-in page you initiate log-in method(s) you choose from the available authorization methods provided by Supabase, below is a simple example for e-mail authentication:
<script setup lang="ts">
const supabase = useSupabaseClient()
const email = ref('')
const signInWithOtp = async () => {
const { error } = await supabase.auth.signInWithOtp({
email: email.value,
options: {
emailRedirectTo: 'http://localhost:3000/welcome',
},
})
if (error) console.log(error)
}
</script>
<template>
<div>
<button @click="signInWithOtp">Sign In with E-Mail</button>
<input
v-model="email"
type="email"
/>
</div>
</template>
⚠️ Ensure to activate and configure the authentication providers you want to use in the Supabase Dashboard underAuthentication -> Providers.
Once the authorization flow is triggered using the auth wrapper of the useSupabaseClient composable, the session management is handled automatically. For the authentication flow PKCE is used, which requires an exchange between your server and the Supabase authentication server for some authentication methods.
When using e-mail authentication, a confirmation e-mail is sent to new users, and an e-mail containing a magic link is sent to existing users. For those links to work with your application, you need to adjust the e-mail templates in your Supabase settings under Authentication -> Email Templates. The generated links must contain a token_hash and type URL parameter, and point to the confirmation URL of your app, which is /auth/confirm by default. In addition you can set the URL parameter redirect_to to determine the route users will be forwarded to in your app when authorization is successful. If redirect_to is omitted, it will route to /. An example template looks like this:
<h2>Confirm your signup</h2>
<p>Hello {{ .Data.first_name }}</p>
<p>Follow this link to confirm your user:</p>
<p>
<a href="{{ .SiteURL }}/supabase/auth/confirm?token_hash={{ .TokenHash }}&type=email&redirect_to={{ .RedirectTo }}>Confirm your email</a
>
</p>
The confirmation route on your server is provided by this module, so you don't need to implement it yourself. It's available at /auth/confirm. It will automatically confirm the user and re-direct to the redirect_to route.
If you want to customize the confirmation route, you can do so by creating a server route to handle the request, and point to it in your Supabase e-mail template. Your custom route will receive the token_hash and type URL parameters, and the redirect_to URL parameter if provided. You can use the useSupabaseClient composable to confirm the user and re-direct to the next route:
⚠️ You can use the provided confirm route at/supabase/confirm, the implementation of a custom route is optional!
import { EmailOtpType } from '@supabase/supabase-js'
import { supabaseServerClient } from '#supabase/server'
export default defineEventHandler(async event => {
const query = getQuery(event)
const token_hash = query.token_hash as string
const type = query.type as EmailOtpType | null
const redirect_to = (query.redirect_to as string) ?? '/'
if (!token_hash || !type) {
throw createError({ statusMessage: 'Invalid token' })
}
const supabase = await supabaseServerClient(event)
const { error } = await supabase.auth.verifyOtp({ type, token_hash })
if (error) {
throw createError({ statusMessage: error.message })
}
await sendRedirect(event, redirect_to, 302)
})When using OAuth authentication, you need to configure the OAuth provider in your Supabase settings under Authentication -> Providers. You can then use the signInWithOAuth method of the auth wrapper of the useSupabaseClient composable to initiate the authorization flow. This module provides a default callback under /auth/callback that you can provide to the authentication function:
const signInWithOAuth = async () => {
const { error } = await supabase.auth.signInWithOAuth({
provider: 'github',
options: {
redirectTo: 'http://<your-site-url>/auth/callback',
},
})
if (error) console.log(error)
}You can customize the callback by creating your own server route, and point to it when calling signInWithOAuth. The callback route will receive a code, that needs to be exchanged for a session. Here is an example:
⚠️ You can use the provided callback route at/auth/callback, the implementation of a custom callback is optional!
import { supabaseServerClient } from '#supabase/server'
export default defineEventHandler(async event => {
const query = getQuery(event)
const code = query.code as string
const redirect_to = (query.redirect_to as string) ?? '/'
if (!code) {
throw createError({ statusMessage: 'No code provided' })
}
const supabase = await supabaseServerClient(event)
const { error } = await supabase.auth.exchangeCodeForSession(code)
if (error) {
throw createError({ statusMessage: error.message })
}
await sendRedirect(event, redirect_to, 302)
})If redirect is set to true in the module options, users will be automatically routed to the login page when they are not authenticated. If you want to allow access to "public" pages, you just need to add them in the exclude redirect option, and they will not re-direct unauthenticated users.
When an authentication error occurs, an exception is thrown. You can create an error page in the root of your app, to show an appropriate error message, clear the error and send the user to an appropriate route to continue. Here is an example for error.vue:
<script setup lang="ts">
import type { H3Error } from 'h3'
const { error } = defineProps<{
error: H3Error
}>()
const handleError = () => clearError({ redirect: '/' })
</script>
<template>
<div>
<h2>{{ error.statusCode }}</h2>
<p>{{ error.message }}</p>
<button @click="handleError">Clear errors</button>
</div>
</template>This composable can be used to make requests to the Supabase API. It's auto-imported and ready to use in your components. It's using supabase-js under the hood, it gives access to the Supabase client and all of its features.
Please check Supabase documentation on how to fully use the Supabase client.
Here is an example of fetching from the database using the Supabase client's select method with Nuxt 3 useAsyncData.
<script setup lang="ts">
const client = useSupabaseClient()
const { data: restaurant } = await useAsyncData('restaurant', async () => {
const { data } = await client.from('restaurants').select('name, location').eq('name', 'My Restaurant Name').single()
return data
})
</script>Based on Supabase Realtime, listen to changes in your PostgreSQL Database and broadcasts them over WebSockets.
To enable it, make sure you have turned on the Realtime API for your table.
Then, listen to changes directly in your Vue page / component:
<script setup lang="ts">
import type { RealtimeChannel } from '@supabase/supabase-js'
const client = useSupabaseClient()
let realtimeChannel: RealtimeChannel
// Fetch collaborators and get the refresh method provided by useAsyncData
const { data: collaborators, refresh: refreshCollaborators } = await useAsyncData('collaborators', async () => {
const { data } = await client.from('collaborators').select('name')
return data
})
// Once page is mounted, listen to changes on the `collaborators` table and refresh collaborators when receiving event
onMounted(() => {
// Real time listener for new workouts
realtimeChannel = client
.channel('public:collaborators')
.on('postgres_changes', { event: '*', schema: 'public', table: 'collaborators' }, () => refreshCollaborators())
realtimeChannel.subscribe()
})
// Don't forget to unsubscribe when user left the page
onUnmounted(() => {
client.removeChannel(realtimeChannel)
})
</script>You can pass Database typings to the client. Check Supabase documentation for further information.
<script setup lang="ts">
import type { Database } from '~/types'
const client = useSupabaseClient<Database>()
</script>The useSupabaseClient composable is providing all methods to manage authorization under useSupabaseClient().auth. For more details please see the supabase-js auth documentation. Here is an example for signing in and out:
⚠️ If you want a full explanation on how to handle the authentication process, please read this section.
<script setup lang="ts">
const supabase = useSupabaseClient()
const signInWithOAuth = async () => {
const { error } = await supabase.auth.signInWithOAuth({
provider: 'github',
options: {
redirectTo: 'http://localhost:3000/confirm',
},
})
if (error) console.log(error)
}
const signOut = async () => {
const { error } = await supabase.auth.signOut()
if (error) console.log(error)
}
</script>Make requests to the Supabase API on server side with the supabaseServerClient service. It provides the same functionality as the useSupabaseClient composable, but it is designed to be used on server routes.
On your server route import the supabaseServerClient from #supabase/server. Please note that supabaseServerClient is returning a promise.
import { supabaseServerClient } from '#supabase/server'
export default eventHandler(async event => {
const client = await supabaseServerClient(event)
const { data } = await client.from('libraries').select('*')
return { libraries: data }
})Make requests with super admin rights to the Supabase API with the supabaseServiceRole service. This function is designed to work only in server routes, there is no Vue composable equivalent.
It provides similar functionality as the supabaseServerClient but it provides a client with super admin rights that can bypass your Row Level Security.
The client is initialized with the SUPABASE_SERVICE_ROLE_KEY you must have in your environment. Checkout the doc if you want to know more about Supabase keys.
⚠️ The service key gives admin access to your database, be careful to not expose it in your client side code or in your git repository.
In your server route use the supabaseServiceRole from #supabase/server.
import { supabaseServiceRole } from '#supabase/server'
export default eventHandler(async event => {
const client = supabaseServiceRole(event)
const { data } = await client.from('rls-protected-table').select()
return { sensitiveData: data }
})