Better Auth + SvelteKit

Overview

This skill encapsulates the Better Auth docs (introduction, concepts, SvelteKit integration) plus Convex/DB guidance so you can bootstrap secure authentication quickly. Pair it with the sveltekit2 + svelte5 skills for general Svelte workflows.

Quick start

1. Review Better Auth concepts (API, CLI, client, cookies, sessions, rate limits, hooks/plugins) in references/setup-and-cli.md.
2. Pick a storage strategy (Convex, Mongo, Postgres/SQLite via Prisma/Drizzle) using references/databases-and-storage.md.
3. Initialize Better Auth (CLI or manual config), create a server instance under src/lib/server/auth.ts, and register it in hooks.server.ts.
4. Follow references/sveltekit-integration.md to wire server loads, actions, remote functions, and client helpers.
5. Configure providers (email/password, OAuth) plus emails, plugins, and custom hooks via references/api-and-client-concepts.md.
6. Exercise flows locally with the Better Auth CLI dev server and your Vitest/Playwright suites.

Workflow

1. Plan auth surface
   • Enumerate flows (signup/login/passwordless/OAuth), environments, and domain requirements (cookies + CSP).
   • Decide where user metadata lives (Better Auth default tables vs Convex/DB) and how to sync it.
2. Bootstrap Better Auth
   • Install packages: better-auth, @better-auth/client, better-auth/sveltekit, provider/database adapters, plus Convex client if needed.
   • Run npx better-auth init (or copy better-auth.config.{ts,js}) and set secrets in .env (JWT, encryption keys, SMTP/OAuth creds).
   • Familiarize yourself with CLI commands (better-auth dev, better-auth routes, better-auth doctor) via references/setup-and-cli.md.
3. Create the server instance
   • Define src/lib/server/auth.ts:

     import { betterAuth } from "better-auth/sveltekit";
     import { convexAdapter } from "@better-auth/adapter-convex"; // or prisma/mongo
     
     export const auth = betterAuth({
       database: convexAdapter({ url: process.env.CONVEX_URL }),
       email: { provider: "resend", from: "auth@example.com" },
       oauth: { providers: [/* github, google, etc. */] },
       session: { rolling: true, cookieName: "session", sameSite: "lax" }
     });
     

   • Register in hooks.server.ts:

     import { auth } from "$lib/server/auth";
     export const handle = auth.handleHooks();
     export const handleFetch = auth.handleFetch;
     

   • Expose helpers (locals.session, locals.user, locals.auth) for load/actions.
4. Wire SvelteKit routes
   • In +layout.server.ts, read locals.auth.validate() to gate protected pages and redirect guests.
   • Implement actions or remote functions for login/signup by calling auth.api.signInPassword (server) or using the browser client.
   • Use depends("auth:session") + invalidate("auth:session") to keep UI reactive after auth mutations.
   • Provide error boundaries and user-friendly messaging per repo conventions.
5. Client usage
   • Instantiate the client side helper once:

     import { createBetterAuthClient } from "@better-auth/client";
     export const authClient = createBetterAuthClient({
       baseURL: "/api/auth",
       fetch: window.fetch
     });
     

   • Use runes to track session state, call authClient.signInPassword, signOut, getSession.
   • For Convex, sync tokens via Better Auth session hooks so Convex client can verify identity.
6. Database + infrastructure
   • Follow adapter-specific steps: Convex functions, Mongo collections (indexes on emails + sessions), Postgres/SQLite via Prisma migrations.
   • Configure email delivery, hooks (before/after user created), plugins, rate limits, and custom claims as described in references/api-and-client-concepts.md.
7. Test & operate
   • Run CLI dev server locally, seed test users via better-auth cli users:create.
   • Cover flows with Vitest/Playwright; mock SMTP/OAuth providers.
   • Monitor cookies/session expiration, rotate secrets, and document any custom hooks.

References

• references/setup-and-cli.md — installation, CLI workflow, API surface, cookies/sessions, rate limits, and troubleshooting.
• references/sveltekit-integration.md — SvelteKit-specific wiring for hooks, load/actions, remote functions, and client helpers.
• references/databases-and-storage.md — Convex DB bridge plus MongoDB/Postgres/SQLite adapters and migration tips.
• references/api-and-client-concepts.md — deep dive into Better Auth API/client, hooks, plugins, OAuth, email, and user/account management.