sveltekit-auth

Auth library for SvelteKit supporting OpenID/OAuth providers

Table of Contents

• Installing
• Setup
  • Handle Hook
  • App Types
  • Server layout file
• Protecting Routes
  • Using the RequireAuth helper
  • Checking the session manually
• Client Helpers
  • use:login and use:logout
  • loginUrl() and logoutUrl()
  • goToLogin() and goToLogout()
• AuthHandler
  • AuthHandler Options
• License

Installing

Using npm:

$ npm install @rabrennie/sveltekit-auth

Using yarn:

$ yarn add @rabrennie/sveltekit-auth

Using pnpm:

$ pnpm add @rabrennie/sveltekit-auth

Setup

Handle Hook

In order to be able to handle the auth routes and populate event.locals you must register a handle hook in src/hooks.server.ts (or src/hooks.server.js if not using typescript). Your hooks file should look like the following:

import type { Handle } from '@sveltejs/kit';

export const handle = AuthHandler(config) satisfies Handle

or if using more than one handle function

import type { Handle } from '@sveltejs/kit';
import { sequence } from '@sveltejs/kit/hooks';
import { AuthHandler } from '@rabrennie/sveltekit-auth';

const authHandler = AuthHandler(config) satisfies Handle;

const anotherHandler = (async ({ event, resolve }) => {
    return resolve(event);
}) satisfies Handle;


// You should always have authHandler first in the sequence
export const handle = sequence(authHandler, anotherHandler)

The config options for AuthHandler are defined here.

App Types

You need to tell Sveltekit that we have objects in PageData and Locals so it can correctly type them. Your src/app.d.ts should look like the following:

import type { AuthClient, AuthPageData } from '@rabrennie/sveltekit-auth';

declare global {
    namespace App {
        // ...other types
        interface Locals {
            // ...other types
            auth: AuthClient;
        }
        interface PageData {
            // ...other types
            auth: AuthPageData;
        }
    }
}

export {};

For more information about this see the Sveltekit Docs

Server layout file

In your root /src/+layout.server.ts (or /src/+layout.server.js if not using typescript) you will have to expose the data to the client in order to be able to use the helper methods. You can do this by making the file look like the following:

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async ({ locals }) => {
    return {
        auth: await locals.auth.getAuthPageData(),
    };
};

Protecting Routes

You have a few options to protect routes. You should always do route protection in +page.server.ts (or +page.server.js if not using typescript) files to ensure they are always run for the route.

Using the RequireAuth helper

In your +page.server.ts (or +page.server.js if not using typescript) for a route you can define a load function and wrap it in the RequireAuth helper. If the session is not set the user will be redirected to the loginRoute defined in the AuthHandler config.

Here is an example of using the helper:

import type { PageServerLoad } from './$types';
import { RequireAuth, type Authenticated } from '@rabrennie/sveltekit-auth/helpers';

const loadFunction: Authenticated<PageServerLoad> = async ({ locals }) => {
   const session = await locals.auth.getSession();
   // do something with the session.
};

export const load = RequireAuth(loadFunction);

You can also use this to protect actions in the same way

import type { Actions } from './$types';
import { RequireAuth } from '@rabrennie/sveltekit-auth/helpers';

export const actions = {
    anAction: RequireAuth(async ({ locals }) => {
        const session = await locals.auth.getSession();
        // do something with the session.
    })
} satisfies Actions;

Checking the session manually

In your +page.server.ts (or +page.server.js if not using typescript) for a route you can define a load function and check the session manually.

Here is an example of checking the session manually:

import type { PageServerLoad } from './$types';
import { redirect } from '@sveltejs/kit';

export const load: PageServerLoad = async ({ locals }) => {
    const session = await locals.auth.getSession();
 
    if (!session) {
        throw redirect(302, '/login');
    }
    
    // do something with the session.
 };

You can also use this to protect actions in the same way

import type { Actions } from './$types';
import { redirect } from '@sveltejs/kit';

export const actions = {
    anAction: RequireAuth(async ({ locals }) => {
        const session = await locals.auth.getSession();
 
        if (!session) {
            throw redirect(302, '/login');
        }
        
        // do something with the session.
    })
} satisfies Actions;

Client Helpers

use:login and use:logout

Note these can only be used on DOM elements

You can use these helpers to set the correct handler on an element for logging in and out. For anchor elements this will set the href attribute to the relevant url. For all other elements they will register a click handler that will navigate to the correct url.

Example usage:

<script lang="ts">
    import { login, logout} from '@rabrennie/sveltekit-auth/client';
</script>

<a use:login={'github'}>Log in with GitHub</a>
<button use:logout>Logout</button>

loginUrl() and logoutUrl()

You can use these helpers to get the relevant url for logging in and out.

Example usage:

<script lang="ts">
    import { page } from '$app/stores';
    import { loginUrl, logoutUrl } from '@rabrennie/sveltekit-auth/client';
</script>

<a href={loginUrl($page.data, 'github')}>Log in with GitHub</a>
<a href={logoutUrl($page.data)}>Logout</a>

goToLogin() and goToLogout()

You can use these helpers to navigate to the relevant url for logging in and out.

Example usage:

<script lang="ts">
    import { page } from '$app/stores';
    import { goToLogin, goToLogout } from '@rabrennie/sveltekit-auth/client';
</script>

<button on:click={() => goToLogin($page.data, 'github')}>Log in with GitHub</button>
<button on:click={() => goToLogout($page.data)}>Logout</button>

AuthHandler

AuthHandler Options

Below is the definition for the AuthHandler config. You do not need to provide any of the optional parameters.

export interface AuthHandlerConfig {
    /**
     * Registers all the providers that the current app supports
     *
     * @example [new GithubProvider(config)]
     */
    providers: AuthProvider<AuthProviderConfig, Profile>[];

    /**
     * Registers the session strategy that will be used in the current app.
     *
     * @example new JwtProvider(config)
     */
    sessionStrategy: SessionStrategy<SessionStrategyConfig>;

    /**
     * Allows hooking into certain parts of the auth process. Can be used for features such as persisting user data to database
     * or logging
     */
    hooks?: AuthHandlerHooks;

    /**
     * Changes the "root" path prefix for all routes used by sveltekit-auth. By default this is set to '/auth' and
     * all urls used by sveltekit-auth will start with '/auth' (example: '/auth/redirect/github')
     *
     * @example '/auth'
     * @default '/auth'
     */
    routePrefix?: string;

    /**
     * Changes the part of the path used to match a callback route. By default this is set to '/callback'
     * (example: '/auth/callback/github')
     *
     * @example '/callback'
     * @default '/callback'
     */
    callbackPrefix?: string;

    /**
     * Changes the part of the path used to match a redirect route. By default this is set to '/redirect'
     * (example: '/auth/redirect/github')
     *
     * @example '/redirect'
     * @default '/redirect'
     */
    redirectPrefix?: string;

    /**
     * Changes the part of the path used to match the logout route. By default this is set to '/logout'
     * (example: '/auth/logout')
     *
     * @example '/logout'
     * @default '/logout'
     */
    logoutPrefix?: string;

    /**
     * Where the user will be redirected to when using the RequireAuth helper if they are not logged in
     *
     * @example '/login'
     * @default '/login'
     */
    loginRoute?: string;

    /**
     * Where the user will be redirected to on a successful login
     *
     * @example '/'
     * @default '/'
     */
    loginRedirectRoute?: string;

    /**
     * Where the user will be redirected to after logging out, Defaults to loginRoute
     *
     * @example '/login'
     * @default '/login'
     */
    logoutRoute?: string;
}

License

MIT