---
id: 'sveltekit'
title: 'Supabase Auth with SvelteKit'
description: 'Convenience helpers for implementing user authentication in SvelteKit.'
sidebar_label: 'SvelteKit'
sitemapPriority: 0.5
---
We generally recommend using the new `@supabase/ssr` package instead of `auth-helpers`. `@supabase/ssr` takes the core concepts of the Auth Helpers package and makes them available to any server framework. Check out the [migration doc](/docs/guides/auth/server-side/migrating-to-ssr-from-auth-helpers) to learn more.
This submodule provides convenience helpers for implementing user authentication in [SvelteKit](https://kit.svelte.dev/) applications.
## Configuration
### Install SvelteKit Auth helpers library
This library supports Node.js `^16.15.0`.
```sh Terminal
npm install @supabase/auth-helpers-sveltekit @supabase/supabase-js
```
### Declare environment variables
Retrieve your project's URL and anon key from your [API settings](/dashboard/project/_/settings/api), and create a `.env.local` file with the following environment variables:
```bash .env.local
# Find these in your Supabase project settings https://supabase.com/dashboard/project/_/settings/api
PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_... or anon key
```
### Creating a Supabase client
Create a new `hooks.server.js` file in the root of your project and populate with the following to retrieve the user session.
<$Partial path="get_session_warning.mdx" />
```js src/hooks.server.js
// src/hooks.server.js
import { PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY } from '$env/static/public'
import { createSupabaseServerClient } from '@supabase/auth-helpers-sveltekit'
export const handle = async ({ event, resolve }) => {
event.locals.supabase = createSupabaseServerClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event,
})
/**
* Unlike `supabase.auth.getSession`, which is unsafe on the server because it
* doesn't validate the JWT, this function validates the JWT by first calling
* `getUser` and aborts early if the JWT signature is invalid.
*/
event.locals.safeGetSession = async () => {
const {
data: { user },
error,
} = await supabase.auth.getUser()
if (error) {
return { session: null, user: null }
}
const {
data: { session },
} = await event.locals.supabase.auth.getSession()
return { session, user }
}
return resolve(event, {
filterSerializedResponseHeaders(name) {
return name === 'content-range' || name === 'x-supabase-api-version'
},
})
}
```
Create a new `hooks.server.ts` file in the root of your project and populate with the following:
```ts src/hooks.server.ts
// src/hooks.server.ts
import { PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY } from '$env/static/public'
import { createSupabaseServerClient } from '@supabase/auth-helpers-sveltekit'
import type { Handle } from '@sveltejs/kit'
export const handle: Handle = async ({ event, resolve }) => {
event.locals.supabase = createSupabaseServerClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event,
})
/**
* Unlike `supabase.auth.getSession`, which is unsafe on the server because it
* doesn't validate the JWT, this function validates the JWT by first calling
* `getUser` and aborts early if the JWT signature is invalid.
*/
event.locals.safeGetSession = async () => {
const {
data: { user },
error,
} = await supabase.auth.getUser()
if (error) {
return { session: null, user: null }
}
const {
data: { session },
} = await event.locals.supabase.auth.getSession()
return { session, user }
}
return resolve(event, {
filterSerializedResponseHeaders(name) {
return name === 'content-range' || name === 'x-supabase-api-version'
},
})
}
```
Note that we are specifying `filterSerializedResponseHeaders` here. We need to tell SvelteKit that Supabase needs the `content-range` and `x-supabase-api-version` headers.
### Code Exchange route
The `Code Exchange` route is required for the [server-side auth flow](/docs/guides/auth/server-side-rendering) implemented by the SvelteKit Auth Helpers. It exchanges an auth `code` for the user's `session`, which is set as a cookie for future requests made to Supabase.
Create a new file at `src/routes/auth/callback/+server.js` and populate with the following:
```js src/routes/auth/callback/+server.js
import { redirect } from '@sveltejs/kit'
export const GET = async ({ url, locals: { supabase } }) => {
const code = url.searchParams.get('code')
if (code) {
await supabase.auth.exchangeCodeForSession(code)
}
redirect(303, '/')
}
```
Create a new file at `src/routes/auth/callback/+server.ts` and populate with the following:
```ts src/routes/auth/callback/+server.ts
import { redirect } from '@sveltejs/kit'
export const GET = async ({ url, locals: { supabase } }) => {
const code = url.searchParams.get('code')
if (code) {
await supabase.auth.exchangeCodeForSession(code)
}
redirect(303, '/')
}
```
### Generate types from your database
In order to get the most out of TypeScript and its IntelliSense, you should import the generated Database types into the `app.d.ts` type definition file that comes with your SvelteKit project, where `import('./DatabaseDefinitions')` points to the generated types file outlined in [v2 docs here](/docs/reference/javascript/release-notes#typescript-support) after you have logged in, linked, and generated types through the Supabase CLI.
```ts src/app.d.ts
// src/app.d.ts
import { SupabaseClient, Session, User } from '@supabase/supabase-js'
import { Database } from './DatabaseDefinitions'
declare global {
namespace App {
interface Locals {
supabase: SupabaseClient
safeGetSession(): Promise<{ session: Session | null; user: User | null }>
}
interface PageData {
session: Session | null
user: User | null
}
// interface Error {}
// interface Platform {}
}
}
```
## Authentication
Authentication can be initiated [client](/docs/guides/auth/auth-helpers/sveltekit#client-side) or [server-side](/docs/guides/auth/auth-helpers/sveltekit#server-side). All of the [supabase-js authentication strategies](/docs/reference/javascript/auth-api) are supported with the Auth Helpers client.
Note: The authentication flow requires the [Code Exchange Route](/docs/guides/auth/auth-helpers/sveltekit#code-exchange-route) to exchange a `code` for the user's `session`.
### Client-side
#### Send session to client
To make the session available across the UI, including pages and layouts, it is crucial to pass the session as a parameter in the root layout's server load function.
```js src/routes/+layout.server.js
// src/routes/+layout.server.js
export const load = async ({ locals: { safeGetSession } }) => {
const { session, user } = await safeGetSession()
return {
session,
user,
}
}
```
```ts src/routes/+layout.server.ts
// src/routes/+layout.server.ts
export const load = async ({ locals: { safeGetSession } }) => {
const { session, user } = await safeGetSession()
return {
session,
user,
}
}
```
#### Shared load functions and pages
To utilize Supabase in shared load functions and within pages, it is essential to create a Supabase client in the root layout load.
```ts src/routes/+layout.js
// src/routes/+layout.js
import { PUBLIC_SUPABASE_PUBLISHABLE_KEY, PUBLIC_SUPABASE_URL } from '$env/static/public'
import { createSupabaseLoadClient } from '@supabase/auth-helpers-sveltekit'
export const load = async ({ fetch, data, depends }) => {
depends('supabase:auth')
const supabase = createSupabaseLoadClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event: { fetch },
serverSession: data.session,
})
/**
* It's fine to use `getSession` here, because on the client, `getSession` is
* safe, and on the server, it reads `session` from the `LayoutData`, which
* safely checked the session using `safeGetSession`.
*/
const {
data: { session },
} = await supabase.auth.getSession()
return { supabase, session }
}
```
```ts src/routes/+layout.ts
// src/routes/+layout.ts
import { PUBLIC_SUPABASE_PUBLISHABLE_KEY, PUBLIC_SUPABASE_URL } from '$env/static/public'
import { createSupabaseLoadClient } from '@supabase/auth-helpers-sveltekit'
import type { Database } from '../DatabaseDefinitions'
export const load = async ({ fetch, data, depends }) => {
depends('supabase:auth')
const supabase = createSupabaseLoadClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event: { fetch },
serverSession: data.session,
})
/**
* It's fine to use `getSession` here, because on the client, `getSession` is
* safe, and on the server, it reads `session` from the `LayoutData`, which
* safely checked the session using `safeGetSession`.
*/
const {
data: { session },
} = await supabase.auth.getSession()
return { supabase, session }
}
```
TypeScript types can be [generated with the Supabase CLI](/docs/reference/javascript/typescript-support) and passed to `createSupabaseLoadClient` to add type support to the Supabase client.
Access the client inside pages by `$page.data.supabase` or `data.supabase` when using `export let data`.
The usage of `depends` tells SvelteKit that this load function should be executed whenever `invalidate` is called to keep the page store in sync.
`createSupabaseLoadClient` caches the client when running in a browser environment and therefore does not create a new client for every time the load function runs.
#### Setting up the event listener on the client side
We need to create an event listener in the root `+layout.svelte` file in order to catch Supabase events being triggered.
```svelte src/routes/+layout.svelte
```
The usage of `invalidate` tells SvelteKit that the root `+layout.ts` load function should be executed whenever the session updates to keep the page store in sync.
#### Sign in / sign up / sign out
We can access the Supabase instance in our `+page.svelte` file through the data object.
```svelte src/routes/auth/+page.svelte
```
### Server-side
[Form Actions](https://kit.svelte.dev/docs/form-actions) can be used to trigger the authentication process from form submissions.
```js src/routes/login/+page.server.js
// src/routes/login/+page.server.js
import { fail } from '@sveltejs/kit'
export const actions = {
default: async ({ request, url, locals: { supabase } }) => {
const formData = await request.formData()
const email = formData.get('email')
const password = formData.get('password')
const { error } = await supabase.auth.signUp({
email,
password,
options: {
emailRedirectTo: `${url.origin}/auth/callback`,
},
})
if (error) {
return fail(500, { message: 'Server error. Try again later.', success: false, email })
}
return {
message: 'Please check your email for a magic link to log into the website.',
success: true,
}
},
}
```
```svelte src/routes/login/+page.svelte
```
```js src/routes/login/+page.server.ts
// src/routes/login/+page.server.ts
import { fail } from '@sveltejs/kit'
export const actions = {
default: async ({ request, url, locals: { supabase } }) => {
const formData = await request.formData()
const email = formData.get('email') as string
const password = formData.get('password') as string
const { error } = await supabase.auth.signUp({
email,
password,
options: {
emailRedirectTo: `${url.origin}/auth/callback`,
},
})
if (error) {
return fail(500, { message: 'Server error. Try again later.', success: false, email })
}
return {
message: 'Please check your email for a magic link to log into the website.',
success: true,
}
},
}
```
```svelte src/routes/login/+page.svelte
```
## Authorization
### Protecting API routes
Wrap an API Route to check that the user has a valid session. If they're not logged in the session is `null`.
```ts src/routes/api/protected-route/+server.ts
// src/routes/api/protected-route/+server.ts
import { json, error } from '@sveltejs/kit'
export const GET = async ({ locals: { supabase, safeGetSession } }) => {
const { session } = await safeGetSession()
if (!session) {
// the user is not signed in
throw error(401, { message: 'Unauthorized' })
}
const { data } = await supabase.from('test').select('*')
return json({ data })
}
```
If you visit `/api/protected-route` without a valid session cookie, you will get a 401 response.
### Protecting actions
Wrap an Action to check that the user has a valid session. If they're not logged in the session is `null`.
```ts src/routes/posts/+page.server.ts
// src/routes/posts/+page.server.ts
import { error, fail } from '@sveltejs/kit'
export const actions = {
createPost: async ({ request, locals: { supabase, safeGetSession } }) => {
const { session } = await safeGetSession()
if (!session) {
// the user is not signed in
throw error(401, { message: 'Unauthorized' })
}
// we are save, let the user create the post
const formData = await request.formData()
const content = formData.get('content')
const { error: createPostError, data: newPost } = await supabase
.from('posts')
.insert({ content })
if (createPostError) {
return fail(500, {
supabaseErrorMessage: createPostError.message,
})
}
return {
newPost,
}
},
}
```
If you try to submit a form with the action `?/createPost` without a valid session cookie, you will get a 401 error response.
### Protecting multiple routes
To avoid writing the same auth logic in every single route you can also use the handle hook to
protect multiple routes at once. For this to work with your Supabase session, you need to use
SvelteKit's [sequence helper](https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks) function.
Edit your `/src/hooks.server.js` with the below:
```js src/hooks.server.js
// src/hooks.server.js
import { PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY } from '$env/static/public'
import { createSupabaseServerClient } from '@supabase/auth-helpers-sveltekit'
import { redirect, error } from '@sveltejs/kit'
import { sequence } from '@sveltejs/kit/hooks'
async function supabase({ event, resolve }) {
event.locals.supabase = createSupabaseServerClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event,
})
/**
* Unlike `supabase.auth.getSession`, which is unsafe on the server because it
* doesn't validate the JWT, this function validates the JWT by first calling
* `getUser` and aborts early if the JWT signature is invalid.
*/
event.locals.safeGetSession = async () => {
const {
data: { user },
error,
} = await event.locals.supabase.auth.getUser()
if (error) return { session: null, user: null }
const {
data: { session },
} = await event.locals.supabase.auth.getSession()
return { session, user }
}
return resolve(event, {
filterSerializedResponseHeaders(name) {
return name === 'content-range' || name === 'x-supabase-api-version'
},
})
}
async function authorization({ event, resolve }) {
// protect requests to all routes that start with /protected-routes
if (event.url.pathname.startsWith('/protected-routes') && event.request.method === 'GET') {
const { session } = await event.locals.safeGetSession()
if (!session) {
// the user is not signed in
redirect(303, '/')
}
}
// protect POST requests to all routes that start with /protected-posts
if (event.url.pathname.startsWith('/protected-posts') && event.request.method === 'POST') {
const { session } = await event.locals.safeGetSession()
if (!session) {
// the user is not signed in
throw error(303, '/')
}
}
return resolve(event)
}
export const handle = sequence(supabase, authorization)
```
```ts src/hooks.server.ts
// src/hooks.server.ts
import { type Handle, redirect, error } from '@sveltejs/kit'
import { PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY } from '$env/static/public'
import { createSupabaseServerClient } from '@supabase/auth-helpers-sveltekit'
import { sequence } from '@sveltejs/kit/hooks'
async function supabase({ event, resolve }) {
event.locals.supabase = createSupabaseServerClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event,
})
/**
* Unlike `supabase.auth.getSession`, which is unsafe on the server because it
* doesn't validate the JWT, this function validates the JWT by first calling
* `getUser` and aborts early if the JWT signature is invalid.
*/
event.locals.safeGetSession = async () => {
const {
data: { user },
error,
} = await event.locals.supabase.auth.getUser()
if (error) return { session: null, user: null }
const {
data: { session },
} = await event.locals.supabase.auth.getSession()
return { session, user }
}
return resolve(event, {
filterSerializedResponseHeaders(name) {
return name === 'content-range' || name === 'x-supabase-api-version'
},
})
}
async function authorization({ event, resolve }) {
// protect requests to all routes that start with /protected-routes
if (event.url.pathname.startsWith('/protected-routes') && event.request.method === 'GET') {
const { session } = await event.locals.safeGetSession()
if (!session) {
// the user is not signed in
redirect(303, '/')
}
}
// protect POST requests to all routes that start with /protected-posts
if (event.url.pathname.startsWith('/protected-posts') && event.request.method === 'POST') {
const { session } = await event.locals.safeGetSession()
if (!session) {
// the user is not signed in
throw error(303, '/')
}
}
return resolve(event)
}
export const handle: Handle = sequence(supabase, authorization)
```
## Data fetching
### Client-side data fetching with RLS
For [row level security](/docs/guides/database/postgres/row-level-security) to work properly when fetching data client-side, you need to use `supabaseClient` from `PageData` and only run your query once the session is defined client-side:
```svelte src/routes/+page.svelte
{#if data.session}
client-side data fetching with RLS
{JSON.stringify(loadedData, null, 2)}
{/if}
```
### Server-side data fetching with RLS
```svelte src/routes/profile/+page.svelte
Protected content for {user.email}
{JSON.stringify(tableData, null, 2)}
{JSON.stringify(user, null, 2)}
```
```ts src/routes/profile/+page.ts
// src/routes/profile/+page.ts
import { redirect } from '@sveltejs/kit'
export const load = async ({ parent }) => {
const { supabase, session } = await parent()
if (!session) {
redirect(303, '/')
}
const { data: tableData } = await supabase.from('test').select('*')
return {
user: session.user,
tableData,
}
}
```
## Saving and deleting the session
```ts
import { fail, redirect } from '@sveltejs/kit'
import { AuthApiError } from '@supabase/supabase-js'
export const actions = {
signin: async ({ request, locals: { supabase } }) => {
const formData = await request.formData()
const email = formData.get('email') as string
const password = formData.get('password') as string
const { error } = await supabase.auth.signInWithPassword({
email,
password,
})
if (error) {
if (error instanceof AuthApiError && error.status === 400) {
return fail(400, {
error: 'Invalid credentials.',
values: {
email,
},
})
}
return fail(500, {
error: 'Server error. Try again later.',
values: {
email,
},
})
}
redirect(303, '/dashboard')
},
signout: async ({ locals: { supabase } }) => {
await supabase.auth.signOut()
redirect(303, '/')
},
}
```
## Migration guide [#migration]
### Migrate to 0.10
#### PKCE Auth flow
Proof Key for Code Exchange (PKCE) is the new server-side auth flow implemented by the SvelteKit Auth Helpers. It requires a server endpoint for `/auth/callback` that exchanges an auth `code` for the user's `session`.
Check the [Code Exchange Route steps](/docs/guides/auth/auth-helpers/sveltekit#code-exchange-route) above to implement this server endpoint.
#### Authentication
For authentication methods that have a `redirectTo` or `emailRedirectTo`, this must be set to this new code exchange route handler - `/auth/callback`. This is an example with the `signUp` function:
```ts
await supabase.auth.signUp({
email: 'valid.email@supabase.io',
password: 'sup3rs3cur3',
options: {
emailRedirectTo: 'http://localhost:3000/auth/callback',
},
})
```
### Migrate from 0.8.x to 0.9 [#migration-0-9]
#### Set up the Supabase client [#migration-set-up-supabase-client]
In version 0.9 we now setup our Supabase client for the server inside of a `hooks.server.ts` file.
```js src/lib/db.ts
// src/lib/db.ts
import { createClient } from '@supabase/auth-helpers-sveltekit'
import { env } from '$env/dynamic/public'
// or use the static env
// import { PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY } from '$env/static/public';
export const supabaseClient = createClient(
env.PUBLIC_SUPABASE_URL,
env.PUBLIC_SUPABASE_PUBLISHABLE_KEY
)
```
```js src/hooks.server.ts
// src/hooks.server.ts
import { PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY } from '$env/static/public'
import { createSupabaseServerClient } from '@supabase/auth-helpers-sveltekit'
import type { Handle } from '@sveltejs/kit'
export const handle: Handle = async ({ event, resolve }) => {
event.locals.supabase = createSupabaseServerClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event,
})
/**
* Unlike `supabase.auth.getSession`, which is unsafe on the server because it
* doesn't validate the JWT, this function validates the JWT by first calling
* `getUser` and aborts early if the JWT signature is invalid.
*/
event.locals.safeGetSession = async () => {
const {
data: { user },
error,
} = await event.locals.supabase.auth.getUser()
if (error) return { session: null, user: null }
const {
data: { session },
} = await event.locals.supabase.auth.getSession()
return { session, user }
}
return resolve(event, {
filterSerializedResponseHeaders(name) {
return name === 'content-range' || name === 'x-supabase-api-version'
},
})
}
```
#### Initialize the client [#migration-initialize-client]
In order to use the Supabase library in your client code you will need to setup a shared load function inside the root `+layout.ts` and create a `+layout.svelte` to handle our event listening for Auth events.
```svelte src/routes/+layout.svelte
```
```ts src/routes/+layout.ts
// src/routes/+layout.ts
import { invalidate } from '$app/navigation'
import { PUBLIC_SUPABASE_PUBLISHABLE_KEY, PUBLIC_SUPABASE_URL } from '$env/static/public'
import { createSupabaseLoadClient } from '@supabase/auth-helpers-sveltekit'
import type { LayoutLoad } from './$types'
import type { Database } from '../DatabaseDefinitions'
export const load: LayoutLoad = async ({ fetch, data, depends }) => {
depends('supabase:auth')
const supabase = createSupabaseLoadClient({
supabaseUrl: PUBLIC_SUPABASE_URL,
supabaseKey: PUBLIC_SUPABASE_PUBLISHABLE_KEY,
event: { fetch },
serverSession: data.session,
})
const {
data: { session },
} = await supabase.auth.getSession()
return { supabase, session }
}
```
```svelte src/routes/+layout.svelte
```
#### Set up hooks [#migration-set-up-hooks]
Since version 0.9 relies on `hooks.server.ts` to setup our client, we no longer need the `hooks.client.ts` in our project for Supabase related code.
#### Types [#migration-typings]
```ts src/app.d.ts
// src/app.d.ts
///
// See https://kit.svelte.dev/docs/types#app
// for information about these interfaces
// and what to do when importing types
declare namespace App {
interface Supabase {
Database: import('./DatabaseDefinitions').Database
SchemaName: 'public'
}
// interface Locals {}
interface PageData {
session: import('@supabase/auth-helpers-sveltekit').SupabaseSession
}
// interface Error {}
// interface Platform {}
}
```
```ts src/app.d.ts
// src/app.d.ts
import { SupabaseClient, Session, User } from '@supabase/supabase-js'
import { Database } from './DatabaseDefinitions'
declare global {
namespace App {
interface Locals {
supabase: SupabaseClient
safeGetSession(): Promise<{ session: Session | null; user: User | null }>
}
interface PageData {
session: Session | null
user: User | null
}
// interface Error {}
// interface Platform {}
}
}
```
#### Protecting a page [#migration-protecting-a-page]
```svelte src/routes/profile/+page.svelte