auth.md

outline	deep

Authentication {#auth}

Imported from "void/auth". Client-side helpers imported from "void/client".

defineAuth(config) {#defineauth-config}

Advanced escape hatch for customizing Void's Better Auth config.

import { defineAuth } from 'void/auth';

export default defineAuth(({ defaults }) => ({
  ...defaults,
  trustedOrigins: ['https://example.com'],
}));

Signature:

function defineAuth(config: VoidAuthConfig): VoidAuthConfig;

getUser() {#getuser}

Returns the current authenticated user, or null when no user is present.

import { getUser } from 'void/auth';

const user = getUser();

Signature:

function getUser(): AuthUser | null;

getSession() {#getsession}

Returns the current Better Auth request state, or null.

import { getSession } from 'void/auth';

const state = getSession();

Signature:

function getSession(): AuthState | null;

getAuth(c) {#getauth-c}

Returns the Better Auth instance for the current request, including plugin APIs inferred from auth.ts. Use it with Better Auth plugin helpers or to forward requests to auth.handler.

import { defineHandler } from 'void';
import { getAuth } from 'void/auth';

export const GET = defineHandler((c) => getAuth(c).handler(c.req.raw));

Requires authentication to be enabled. Throws if no instance is available on the request. It is available to anonymous requests too; use requireAuth(c) when a route requires a signed-in user.

Signature:

function getAuth(c: CloudContext): AuthInstance;

requireAuth(c) {#requireauth-c}

Extracts the authenticated user from the request context. Throws a 401 HTTPException if no session is present.

import { defineHandler } from 'void';
import { requireAuth } from 'void/auth';

export const GET = defineHandler((c) => {
  const user = requireAuth(c);
  return { email: user.email };
});

Signature:

function requireAuth(c: CloudContext): AuthUser;

AuthUser {#authuser}

Better Auth user shape re-exported by Void. It also includes the fields that Better Auth plugins and user.additionalFields in auth.ts add, for example role from admin() or a custom plan field. Your tsconfig needs the generated Void types for this; see Type Safety setup.

interface AuthUser {
  id: string;
  email: string;
  emailVerified: boolean;
  name: string;
  image?: string | null;
  createdAt: Date;
  updatedAt: Date;
}

AuthSession {#authsession}

Better Auth session shape re-exported by Void. It also includes the session fields that Better Auth plugins in auth.ts add, for example impersonatedBy from admin().

interface AuthSession {
  id: string;
  token: string;
  userId: string;
  expiresAt: Date;
  createdAt: Date;
  updatedAt: Date;
  ipAddress?: string | null;
  userAgent?: string | null;
}

::: tip Types inside auth.ts In auth.ts and its imports, let Better Auth infer hook types or use its User and Session types. Using Void's inferred auth types or auth helper results there creates a circular reference. Callbacks such as sendResetPassword receive Better Auth's base User type. :::

AuthState {#authstate}

Combined authenticated request state:

interface AuthState {
  user: AuthUser;
  session: AuthSession;
}

auth {#auth-1}

Imported from "void/client". This is a ready-to-use Better Auth client instance preconfigured with basePath: "/api/auth".

import { auth } from 'void/client';

await auth.signIn.email({ email, password });
await auth.signOut();

The exact client methods come from Better Auth. In pages apps, Void automatically chooses the framework-specific Better Auth client package when available.

For regular SPA apps that use Void for API/file routes without Void Pages mode, import the framework-specific client explicitly:

import { auth } from 'void/client/react';
// or: 'void/client/vue'
// or: 'void/client/svelte'
// or: 'void/client/solid'

Those subpaths keep the same fetch, fetchStream, and auth exports as void/client, but bind auth and createAuthClient to Better Auth's framework package.

createAuthClient {#createauthclient}

Imported from "void/client". Re-export of Better Auth's createAuthClient for advanced usage.

import { createAuthClient } from 'void/client';

const auth = createAuthClient({ basePath: '/api/auth' });