better-sveltekit-convex-client

SSR-safe Convex client setup and query helpers for SvelteKit.

Install

pnpm add better-sveltekit-convex-client convex

Usage

Setup in root layout

<script lang="ts">
    import { PUBLIC_CONVEX_URL } from "$env/static/public";
    import { setupConvexClient } from "better-sveltekit-convex-client";
    import { fetchConvexToken } from "$lib/auth/convex-token";

    let { data } = $props();

    setupConvexClient({
        convexUrl: PUBLIC_CONVEX_URL,
        fetchToken: fetchConvexToken,
        getServerState: () => data?.authState,
    });
</script>

Access auth state

import { useConvexAuth } from "better-sveltekit-convex-client";

const convexAuth = useConvexAuth();

Subscribe to queries

import { useQuery } from "better-sveltekit-convex-client";
import { api } from "$convex/_generated/api";

const usersQuery = useQuery(api.users.list, () => ({}));

Skip queries conditionally

const activeUser = useQuery(
    api.users.getActive,
    () => (isAuthed ? {} : "skip")
);

Map _id to id

import { useQueryMapped } from "better-sveltekit-convex-client";

const clientsQuery = useQueryMapped(api.clients.list, () => ({}));

API

• setupConvexClient({ convexUrl, fetchToken, getServerState, clientOptions })
• useConvexClient()
• useConvexClientWrapper()
• useConvexAuth()
• useQuery()
• useQueryMapped()
• combineQueries()

Notes

• This library is auth-provider agnostic. Provide your own fetchToken() function.
• Designed for Svelte 5 runes ($state, $effect, $derived).
• Requires SvelteKit ($app/environment).

License

MIT