Svelte bindings for Convex Auth v2 (@convex-dev/auth@2). The API mirrors upstream's React and Next.js clients, so upstream's docs for the backend apply as they are.
pnpm add @mmailaender/convex-auth-svelte@alpha @convex-dev/auth convex convex-svelteThen follow the guide for your app:
| Guide | For |
|---|---|
| SvelteKit | SvelteKit with server-side rendering. The refresh token stays in an httpOnly cookie, and pages render signed in on the first request. |
| Svelte | Client-only apps. The tokens live in localStorage, or in the storage you pass. |
Version 1.x supports Convex Auth v2 only. Apps on Convex Auth v1 (@convex-dev/auth@0.0.x) stay on @mmailaender/convex-auth-svelte@0.1.x.
Each method has the helpers of upstream's React client, from @mmailaender/convex-auth-svelte/methods/<method>:
| Method | Helpers |
|---|---|
| Username + password | useSignInWithUsernamePassword, useSignUpWithUsernamePassword |
| Email + password | Sign-in, sign-up with a validation link, password reset and email change, e.g. useSignUpWithEmailPassword, useStartPasswordRecovery |
| Passkeys | useSignInWithUsernamePasskey, with browser autofill, plus useAddPasskey and useRemovePasskey |
| Google, Apple, GitHub | useSignInWithGoogle, useSignInWithApple, useSignInWithGithub |
The demo in src/routes has UI for every method above, and the account management that comes with each: profile, avatar, change email and password, and passkeys. Copy the components you need from src/demo. They aren't part of the package.
Convex Auth v2 is a rewrite. The backend moves to components and per-method setup functions, so start with upstream's migration notes. v2 has fewer sign-in methods than v1 at launch (no magic links, OTP, anonymous sign-in or arbitrary Auth.js providers), and upstream's migration tooling for existing user data isn't out yet.
On the Svelte side, the API now mirrors upstream's React and Next.js clients. The migration sections of the SvelteKit and Svelte guides show each change as a before/after:
useAuth()from this package is gone: the state comes fromuseAuth()ofconvex-svelte, and the actions fromuseAuthActions().signIn(provider, params)is gone: each method has the helpers of upstream's React client, e.g.useSignInWithUsernamePassword(api.auth).- SvelteKit:
createConvexAuthHooksandcreateConvexAuthHandlersbecomesetupConvexAuthSvelteKit, and sign-in goes through three auth routes from upstream instead ofPOST /api/auth. The refresh token no longer reaches page data.
See docs/upstreaming.md for how this maps onto @convex-dev/auth and what a PR there could share.
pnpm dev runs the reference app against the Convex deployment in .env.local. / is the SvelteKit app and /spa the client-only one. See src/demo/README.md for the environment variables, and e2e/README.md to run the tests.
