Skip to content
brought to you byVoidZero

Authentication ​

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

defineAuth(config) ​

Customize Better Auth in a root-level auth.ts file. Spread defaults to keep Void's configuration:

ts
import { defineAuth } from 'void/auth';

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

Signature:

ts
function defineAuth(config: VoidAuthConfig): VoidAuthConfig;

getUser() ​

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

ts
import { getUser } from 'void/auth';

const user = getUser();

Signature:

ts
function getUser(): AuthUser | null;

getSession() ​

Returns the current user and session, or null when signed out.

ts
import { getSession } from 'void/auth';

const state = getSession();

Signature:

ts
function getSession(): AuthState | null;

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.

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

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

Enable authentication before calling this helper; it throws if no instance is available. Anonymous requests can use it too. Call requireAuth(c) separately to require a signed-in user.

Void includes cookies set by getAuth(c).api calls in the response. For example, signInEmail and signUpEmail sign in the current browser. A cross-origin POST must come from a configured trustedOrigins entry for those cookies to be sent. See Calling Better Auth APIs for session updates and account creation.

Signature:

ts
function getAuth(c: CloudContext): AuthInstance;

requireAuth(c, options?) ​

Returns the signed-in user or throws a 401 HTTPException if no session is present:

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

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

In a page loader or middleware, that exception shows the nearest applicable _error component. To send visitors to login instead, pass throwRedirect:

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

export const loader = defineHandler((c) => {
  const user = requireAuth(c, { throwRedirect: '/login' });
  return { email: user.email };
});

throwRedirect works in loaders, actions, and middleware. For a signed-out request, it stops execution with a 302 redirect for GET/HEAD requests or 303 for other methods. Pages client navigation follows the redirect without a document reload. Signing in does not repeat a rejected action.

Choose a trusted destination in your app; validate any URL supplied by a user before passing it here.

Signature:

ts
function requireAuth(c: CloudContext, options?: { throwRedirect?: string }): 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.

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

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().

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

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 ​

Combined authenticated request state:

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

auth ​

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

ts
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:

ts
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 ​

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

ts
import { createAuthClient } from 'void/client';

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