Better Auth
Better Auth
Section titled “Better Auth”Authentication, not authorization. This page answers who the user is. Whether they may perform a given action is a separate question, answered by
AccessService. The two are independent: a user can be fully authenticated and still be refused a capability, and that refusal is a403, not a401.
Better Auth is a framework-agnostic auth server for
TypeScript. This adapter adds three things on top of the official integrations:
- One client factory for five frameworks — only the entry you ask for is imported.
- Safe Result wrappers for the server calls, so a failed session lookup never throws inside middleware or a route handler.
- Social provider validation — every vendor in one checked call, so a missing environment variable fails at startup instead of at sign-in.
The server itself is still Better Auth’s: mount auth.handler, keep betterAuth()
exactly as the official docs describe.
Install
Section titled “Install”bun add better-authbetter-auth is an optional peer dependency — only imported when you call the adapter.
Server — handler, session, locals
Section titled “Server — handler, session, locals”import { betterAuth } from "better-auth";
export const auth = betterAuth({/* storage, socialProviders, plugins… */});Mount the handler (Astro)
Section titled “Mount the handler (Astro)”import type { APIRoute } from "astro";import { auth } from "~/auth";import { useAuthHandler } from "katanakit-js/adapters/better-auth";
export const ALL: APIRoute = async ({ request }) => { const result = await useAuthHandler(auth, request); return result.ok ? result.data : new Response("Auth unavailable", { status: 500 });};Middleware → Astro.locals
Section titled “Middleware → Astro.locals”import { defineMiddleware } from "astro:middleware";import { auth } from "~/auth";import { useAstroAuthLocals } from "katanakit-js/adapters/better-auth";
export const onRequest = defineMiddleware(async (context, next) => { const locals = await useAstroAuthLocals(auth, context.request); if (locals.ok) { context.locals.user = locals.data.user; context.locals.session = locals.data.session; } return next();});Anonymous visitors resolve to { user: null, session: null } with ok: true —
only a real failure returns ok: false.
Read the session anywhere server-side
Section titled “Read the session anywhere server-side”import { useAuthSession } from "katanakit-js/adapters/better-auth";
const session = await useAuthSession(auth, request); // Request | Headers | { headers }if (session.ok && session.data) { console.log(session.data.user.email);}Social providers — one call, every vendor
Section titled “Social providers — one call, every vendor”Better Auth ships 36 social providers (Google, GitHub, Discord, Microsoft,
LinkedIn, Apple, TikTok, Notion, Spotify…). useSocialProviders validates your
socialProviders before betterAuth() ever sees it, so a missing environment
variable fails at startup instead of when a visitor clicks Sign in with
Google.
// auth.ts — top-level await is fine in ESMimport { betterAuth } from "better-auth";import { useSocialProviders } from "katanakit-js/adapters/better-auth";
const social = await useSocialProviders({ google: { clientId: process.env.GOOGLE_CLIENT_ID ?? "", clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? "", }, github: { clientId: process.env.GITHUB_CLIENT_ID ?? "", clientSecret: process.env.GITHUB_CLIENT_SECRET ?? "", }, discord: { clientId: process.env.DISCORD_CLIENT_ID ?? "", clientSecret: process.env.DISCORD_CLIENT_SECRET ?? "", },});
if (!social.ok) throw new Error(social.error.message);
export const auth = betterAuth({ socialProviders: social.data /* storage, plugins… */,});The result carries the same object you passed in — spread it straight into
socialProviders. Every problem in the configuration is reported at once:
| Message | Meaning |
|---|---|
unknown provider |
The id is not in the installed Better Auth catalog (a typo, or a vendor your peer version dropped). The message lists the ids that do exist. |
missing a client identifier |
Neither clientId nor clientKey was configured. |
clientId is empty |
An unset environment variable — ?? "" makes it typecheck, not work. |
clientSecret is empty / clientId is an empty array |
Same class of mistake. |
Two configurations are passed through untouched, because their credentials only exist inside Better Auth:
await useSocialProviders({ google: () => ({ clientId: load("GOOGLE_ID"), clientSecret: load("GOOGLE_SECRET"), }), // thunk tiktok: { enabled: false }, // switched off — nothing to configure});::: warning clientSecret is validated but never required
TikTok identifies itself with clientKey (no clientId), and public PKCE
clients carry no secret — so demanding both would reject valid setups. Type
checking still enforces each vendor’s own required fields; the helper only
catches what TypeScript cannot see: empty values and unknown ids.
:::
Client — five frameworks, one factory
Section titled “Client — five frameworks, one factory”import { useAuthClient } from "katanakit-js/adapters/better-auth";
// vanilla (no framework, plain <script>)const authClient = await useAuthClient();
// the four framework entries — only the one you pick is bundledconst vue = await useAuthClient({ framework: "vue" });const react = await useAuthClient({ framework: "react" });const svelte = await useAuthClient({ framework: "svelte" });const solid = await useAuthClient({ framework: "solid" });The return type follows the framework, so destructuring keeps Better Auth’s own types:
// lib/auth-client.ts (Vue)import { useAuthClient } from "katanakit-js/adapters/better-auth";
export const authClient = await useAuthClient({ framework: "vue" });export const { signIn, signUp, signOut, useSession } = authClient;Options are Better Auth’s BetterAuthClientOptions:
const authClient = await useAuthClient({ framework: "react", baseURL: "https://auth.example.com", plugins: [/* organization(), twoFactor() … */],});| Function | Returns | Fails when |
|---|---|---|
useAuthClient(options?) |
Framework-typed auth client | the entry cannot be imported |
useAuthSession(auth, request) |
Session | null |
the API call throws |
useAuthHandler(auth, request) |
Response |
the handler throws |
useAstroAuthLocals(auth, request) |
{ user, session } |
the session lookup fails |
useSocialProviders(providers) |
The validated socialProviders |
a credential is empty, missing or unknown |
Everything returns { data, error, ok } — no try/catch at the call site.
Other frameworks
Section titled “Other frameworks”Better Auth ships its own integrations for Next.js (better-auth/next-js),
SvelteKit (better-auth/svelte-kit), SolidStart, TanStack Start and Node
(better-auth/node). Use those directly; this adapter covers the client factory
and the Safe Result server helpers.