Svelte Clerk

Community package that integrates Clerk with SvelteKit.

[!IMPORTANT] This package requires Svelte 5 and uses runes and snippets under the hood. If you're using Svelte 4, please refer to clerk-sveltekit.

Installation

npm install svelte-clerk

Set environment variables

PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxx
CLERK_SECRET_KEY=sk_test_xxxxxxx

Add server handler

import { withClerkHandler } from 'svelte-clerk/server';

export const handle = withClerkHandler();

Update app.d.ts

Inside your src/ directory, update the app.d.ts file to ensure that the locals added by the Clerk handler are properly typed.

/// <reference types="svelte-clerk/env" />

declare global {
    namespace App {...}
}

This handler will inject the Auth object to event.locals.

Add <ClerkProvider> to your root layout

All Clerk runes and components must be children of the <ClerkProvider> component, which provides active session and user context.

// src/+layout.server.ts
import { buildClerkProps } from 'svelte-clerk/server';

// To enable Clerk SSR support, pass the `initialState` to the `ClerkProvider` component.
export const load = ({ locals }) => {
    return {
        ...buildClerkProps(locals.auth)
    };
};

<script lang="ts">
    import type { Snippet } from '@svelte';
    import type { LayoutData } from './$types';
    import { ClerkProvider } from 'svelte-clerk';
    import { PUBLIC_CLERK_PUBLISHABLE_KEY } from '$env/static/public';

    const {
        children,
        data
    }: {
        children: Snippet;
        data: LayoutData;
    } = $props();
</script>

<!-- ... -->

<ClerkProvider {...data} publishableKey={PUBLIC_CLERK_PUBLISHABLE_KEY}>
    {@render children()}
</ClerkProvider>

Components

• <ClerkLoaded>
• <ClerkLoading>
• <Protect>
• <SignedIn>
• <SignedOut>
• <SignIn>
• <SignUp>
• <UserButton>
• <UserProfile>
• <OrganizationProfile>
• <OrganizationSwitcher>
• <CreateOrganization>
• <GoogleOneTap>

Runes

• auth - Auth state.
• user - Authenticated user.
• organization - Active Organization of the authenticated user.
• session - Session of the authenticated user.
• sessionList - Sessions of the current Clerk client.
• signIn - See SignIn.
• signUp - See SignUp.
• clerk - See Clerk.

Example:

The following example demonstrates how to use the auth rune to access the current auth state, like whether the user is signed in or not. It also demonstrates a basic example of how you could use the getToken() method to retrieve a session token for fetching data from an external resource.

<script>
    import { useClerkContext } from 'svelte-clerk';

    // Do not destructure context or you'll lose reactivity!
    const ctx = useClerkContext();
    const userId = $derived(ctx.auth.userId);

    const fetchDataFromExternalResource = async () => {
        const token = await ctx.session.getToken();
        // Add logic to fetch your data
        return data;
    };
</script>

{#if userId === undefined}
    <p>Loading...</p>
{:else if userId === null}
    <p>Sign in to view this page</p>
{:else}
    <div>...</div>
{/if}

Protecting routes

Client side

Clerk offers Control Components that allow you to protect your pages. These components are used to control the visibility of your pages based on the user's authentication state.

<script>
    import { SignedIn, SignedOut, UserButton, SignOutButton } from 'svelte-clerk';
</script>

<div>
    <h1>Index Route</h1>
    <SignedIn>
        <p>You are signed in!</p>
        <div>
            <p>View your profile here 👇</p>
            <UserButton />
        </div>
        <div>
            <SignOutButton />
        </div>
    </SignedIn>
    <SignedOut>
        <p>You are signed out</p>
        <div>
            <a href="/sign-in">Go to Sign in</a>
        </div>
        <div>
            <a href="/sign-up">Go to Sign up</a>
        </div>
    </SignedOut>
</div>

Server side

To protect your routes, you can use the load function to check for the userId singleton. If it doesn't exist, redirect your user back to the sign-in page.

import { redirect } from '@sveltejs/kit';
import { clerkClient } from 'svelte-clerk/server';

export const load = ({ locals }) => {
    const { userId } = locals.auth;

    if (!userId) {
        return redirect(307, '/sign-in');
    }

    const user = await clerkClient.users.getUser(userId);

    return {
        user: JSON.parse(JSON.stringify(user))
    };
};

Advanced usage

This example uses a custom Security class to handle the authorization logic. It is a good practice if you find yourself repeating the same logic across multiple routes.

In a utility file create a class that can provide multiple authorization methods which will trigger an appropriate http response in the event of a failed check:

// utils/Security.ts
import { error, redirect, type RequestEvent } from '@sveltejs/kit';
import { withClerkHandler } from 'svelte-clerk/server';
import type { AuthObject } from '@clerk/backend/internal';

export class Security {
    private readonly auth?: AuthObject;

    constructor(private readonly event: RequestEvent) {
        this.auth = event.locals.auth;
    }

    isAuthenticated() {
        if (!this.auth?.userId) {
            redirect(307, '/sign-in');
        }
        return this;
    }

    hasPermission(permission: string) {
        const permitted = this.auth?.has({ permission });
        if (!permitted) {
            error(403, 'missing permission: ' + permission);
        }
        return this;
    }
}

Inject the Security class into the event locals so that it can be accessed in the load function:

// hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import { Security } from '$lib/utils';

export const handle = sequence(withClerkHandler(), ({ event, resolve }) => {
    event.locals.security = new Security(event);

    return resolve(event);
});

And use it in your routes:

// src/routes/admin/+page.server.ts

export const load = ({ locals: { securty, auth } }) => {
    // Restrict route to users with specific permissions
    security.hasPermission('org:sys_memberships:manage').hasPermission('org:sys_domains_manage');

    const project = await getProject(auth.userId);

    return { project };
};

If you're planning to add authorization logic within a +layout.server.ts, I recommend reading this blog post first.

TODO

• Custom pages
• Redirect to sign in page with redirectToSignIn (add to auth local)
• E2E tests with basic flows

License

MIT