Vanilla Client

The vanilla client can be used with any frontend setup. It’s perfect for:

• Backend-only auth setups (Bun.serve, Elysia, etc.)
• Frameworks not yet supported by gau
• Frameworkless apps

1. Set up your backend

   Follow one of the backend-only integration guides:

   Bun.serve

   Elysia

   Or use createHandler from @rttnd/gau/core with any framework that supports standard Request/Response objects.

2. Create the client

   Import createAuthClient and initialize it with your auth API base URL:

   src/auth.ts

   import process from 'node:process'
   import { createAuthClient } from '@rttnd/gau/client/vanilla'
   import type { Auth } from './server/auth'
   
   export const auth = createAuthClient<Auth>({
     baseUrl: process.env.AUTH_BASE_URL, // http://localhost:3000/api/auth in dev
   })

   Note

   The Auth type import is optional but provides better types for your configured providers.

3. Use the client

   The client provides methods to manage authentication:

   Fetch Session

   const session = await auth.fetchSession()
   console.log(session.user) // User | null

   Sign In

   Redirects to OAuth provider

   await auth.signIn('github', {
     redirectTo: '/dashboard', // Optional
   })

   Sign Out

   await auth.signOut()

   Link Account

   await auth.linkAccount('google', {
     redirectTo: '/profile',
   })

   Unlink Account

   await auth.unlinkAccount('google')

   Refresh Session

   await auth.refreshSession()

   Use a Server Session

   Start with the safe session returned by your server helper:

   const auth = createAuthClient({ baseUrl: '/api/auth', session })

   After navigation, apply fresh server data with auth.setSession(session). This updates subscribers without making a request. To fetch current data from the server instead, use auth.refreshSession().

   Create shared clients only in browser code. On the server, keep each visitor’s session separate.

   Listen to Session Changes

   const unsubscribe = auth.onSessionChange((session) => {
     console.log('Session updated:', session)
     // Update UI, store in state management, etc.
   })
   
   // Later: clean up listener
   unsubscribe()

   Handle Redirect Callbacks

   After OAuth redirects back to your app, handle the callback:

   const handled = await auth.handleRedirectCallback((url) => {
     window.history.replaceState({}, '', url) // Example
   })
   
   if (handled) {
     console.log('OAuth callback handled, session updated')
   }

4. Next Steps

   • Learn about Session Management
   • Explore OAuth Providers
   • See Security best practices

Session Token Storage

The vanilla client stores and retrieves session tokens using:

• localStorage.getItem('gau-token')
• document.cookie for __gau-session-token

API Reference

createAuthClient<TAuth>(options)

Creates a new auth client instance.

Options:

• baseUrl (required): Base URL of your auth API

Returns:

• fetchSession(): Fetches the current session from the server
• refreshSession(): Alias for fetchSession(), refreshes the session
• applySessionToken(token): Applies a session token manually
• onSessionChange(listener): Subscribes to session changes, returns unsubscribe function
• handleRedirectCallback(replaceUrl?): Handles OAuth redirect callbacks
• signIn(provider, options?): Initiates sign-in flow
• signOut(): Signs out the user
• linkAccount(provider, options?): Links an additional OAuth account
• unlinkAccount(provider): Unlinks an OAuth account