Framework Integrations

gau is designed to be framework-agnostic. It can run anywhere, but official support makes it easier.

It provides client-side components and hooks for frameworks. This section covers the common features and options available across all client integrations.

gau has support for full-stack frameworks:

SvelteKit

SolidStart

And backend-only frameworks:

Bun.serve

Elysia

For backend-only setups, you can use the vanilla client on the frontend:

Vanilla

AuthProvider

To get started, you need to wrap your application’s root component with the AuthProvider. This component manages the authentication state and makes it available throughout your app.

Props

You can configure the AuthProvider with the following props:

baseUrl

Type: string Default: '/api/auth'

The base URL for the authentication API endpoints. This should match the basePath configured in your createAuth setup on the server.

Note

If your frontend and backend are on different hosts, you’ll need to set this to the full URL of your backend’s auth API.

scheme

Type: string Default: 'gau'

The URL scheme used for deep linking in desktop applications (e.g., Tauri). This is used to redirect the user back to your app after they have authenticated with an OAuth provider.

redirectTo

Type: string Default: The current host URL

A default URL to redirect to after a successful sign-in. This can be overridden by passing a redirectTo option to the signIn function.

useAuth

The useAuth hook is the primary way to access authentication state and methods in your components.

Return Values

The useAuth hook returns an object with the following properties:

session

Type: GauSession

An object containing the current authentication state. Its user and session properties will be null if the user is not authenticated.

• user: The user object from the database, or null.
• session: The session object containing the raw JWT payload, or null.
• accounts: An array of OAuth accounts linked to the user, or null.
• providers: An array of available provider IDs.

isLoading

Type: boolean

A boolean indicating whether the initial session fetch is still in progress. This is useful for showing loading states in your UI.

Note

This property is only available in the Svelte client. The Solid client uses Solid’s resource system which has its own loading state.

signIn

Type: (provider: string, options?: { redirectTo?: string }) => Promise<void>

A function to initiate the sign-in process with a specific OAuth provider.

• provider: The ID of the provider to use (e.g., 'github', 'google').
• options.redirectTo: A URL to redirect to after a successful sign-in, overriding the default redirectTo prop on the AuthProvider.

Note

You can get full TypeScript support for your provider IDs by creating a typed useAuth hook. See the framework integration guides for examples.

signOut

Type: () => Promise<void>

A function to sign the user out, clearing their session.

linkAccount

Type: (provider: string, options?: { redirectTo?: string }) => Promise<void>

A function to initiate the OAuth flow to manually link an additional provider to the currently authenticated user’s account.

• provider: The ID of the provider to link (e.g., 'github', 'google').
• options.redirectTo: A URL to redirect to after a successful link, overriding the default redirectTo prop on the AuthProvider.

unlinkAccount

Type: (provider: string) => Promise<void>

A function to unlink an OAuth provider from the user’s account.

• provider: The ID of the provider to unlink.

Caution

A user cannot unlink their last remaining account, as this would leave them with no way to sign in. gau will prevent this action and return an error.

refresh

Type: () => Promise<void>

A function to manually refresh the session from the server. This fetches the latest session data and updates the local state.

This might be useful when:

• You’ve updated user data on the server and want to reflect changes immediately
• You want to check if the session is still valid
• You’ve linked or unlinked accounts and want to update the accounts list