Installation & Setup

Install

npm install @authrim/sveltekit

Peer dependencies: svelte ^4.0.0 || ^5.0.0, @sveltejs/kit ^2.0.0.

Setup (5 Steps)

Step 1: Auth Configuration

Create src/lib/auth.ts — a singleton factory for the Authrim client:

src/lib/auth.ts

import { createAuthrim, type AuthrimClient } from '@authrim/sveltekit';

let auth: AuthrimClient | null = null;

export async function getAuth(): Promise<AuthrimClient> {
  if (auth) return auth;

  auth = await createAuthrim({
    issuer: import.meta.env.PUBLIC_AUTHRIM_ISSUER,
    clientId: import.meta.env.PUBLIC_AUTHRIM_CLIENT_ID,
  });

  return auth;
}

export function clearAuth(): void {
  if (auth) {
    auth.destroy();
    auth = null;
  }
}

Step 2: Server Hook

Create src/hooks.server.ts — the server-side handle hook:

src/hooks.server.ts

import { createAuthHandle } from '@authrim/sveltekit/server';

export const handle = createAuthHandle({
  callbackPaths: ['/callback'],
});

This reads the session cookie on every request and populates event.locals.auth.

Step 3: TypeScript Types

Add to src/app.d.ts:

src/app.d.ts

import type { ServerAuthContext } from '@authrim/sveltekit/server';

declare global {
  namespace App {
    interface Locals {
      auth?: ServerAuthContext;
    }
    interface PageData {
      auth: ServerAuthContext | null;
    }
  }
}

export {};

Step 4: Root Layout

Server layout — pass auth context from SSR:

src/routes/+layout.server.ts

import { createAuthLoad } from '@authrim/sveltekit/server';

export const load = createAuthLoad();

Client layout — initialize AuthProvider with SSR data:

src/routes/+layout.svelte

<script lang="ts">
  import { onMount } from 'svelte';
  import { AuthProvider } from '@authrim/sveltekit/components';
  import type { AuthrimClient } from '@authrim/sveltekit';

  let { data, children } = $props();

  let auth: AuthrimClient | null = $state(null);

  onMount(async () => {
    const { getAuth } = await import('$lib/auth');
    auth = await getAuth();
  });
</script>

{#if auth}
  <AuthProvider
    {auth}
    initialSession={data.auth?.session ?? null}
    initialUser={data.auth?.user ?? null}
  >
    {@render children()}
  </AuthProvider>
{:else}
  <p>Loading...</p>
{/if}

Svelte 4

In Svelte 4, use export let data for props and <slot /> instead of {@render children()}:

<script lang="ts">
  export let data;
  // ...
</script>
<!-- ... -->
<AuthProvider ...>
  <slot />
</AuthProvider>

Step 5: First Page

Create a login page:

src/routes/login/+page.svelte

<script lang="ts">
  import { getAuthContext } from '@authrim/sveltekit';
  import { goto } from '$app/navigation';

  const auth = getAuthContext();
  const { isAuthenticated } = auth.stores;

  let loading = $state(false);
  let error = $state('');

  async function handlePasskeyLogin() {
    loading = true;
    error = '';

    const { data, error: err } = await auth.passkey.login();

    if (err) {
      error = err.message;
      loading = false;
      return;
    }

    goto('/');
  }
</script>

{#if $isAuthenticated}
  <p>Already signed in. <a href="/">Go home</a></p>
{:else}
  <button onclick={handlePasskeyLogin} disabled={loading}>
    {loading ? 'Signing in...' : 'Sign in with Passkey'}
  </button>

  {#if error}
    <p>{error}</p>
  {/if}
{/if}

Svelte 4

In Svelte 4, use on:click instead of onclick:

<button on:click={handlePasskeyLogin} disabled={loading}>

Environment Variables

Variable	Description
PUBLIC_AUTHRIM_ISSUER	Authrim server URL (e.g., https://auth.example.com)
PUBLIC_AUTHRIM_CLIENT_ID	OAuth client ID from the Admin panel

Add these to .env:

PUBLIC_AUTHRIM_ISSUER=https://auth.example.com
PUBLIC_AUTHRIM_CLIENT_ID=my-app

Project Structure

src/
├── app.d.ts                  # Type declarations
├── hooks.server.ts           # Server hook (createAuthHandle)
├── lib/
│   └── auth.ts               # Auth client singleton
└── routes/
    ├── +layout.server.ts     # SSR auth data
    ├── +layout.svelte        # AuthProvider wrapper
    ├── +page.svelte           # Home page
    ├── login/
    │   └── +page.svelte       # Login page
    ├── signup/
    │   └── +page.svelte       # Signup page
    ├── callback/
    │   └── +page.svelte       # Social login callback
    └── account/
        └── +page.svelte       # Account settings

Next Steps

• Server-Side Integration — Deep dive into server hooks
• Authentication — All authentication methods
• Components — Pre-built Svelte components