Skip to content

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 a 403, not a 401.

Better Auth is a framework-agnostic auth server for TypeScript. This adapter adds three things on top of the official integrations:

  1. One client factory for five frameworks — only the entry you ask for is imported.
  2. Safe Result wrappers for the server calls, so a failed session lookup never throws inside middleware or a route handler.
  3. 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.

Terminal window
bun add better-auth

better-auth is an optional peer dependency — only imported when you call the adapter.

import { betterAuth } from "better-auth";
export const auth = betterAuth({/* storage, socialProviders, plugins… */});
src/pages/api/auth/[...all].ts
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 });
};
src/middleware.ts
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.

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 ESM
import { 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. :::

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 bundled
const 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.

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.