--- name: better-auth-tauri-setup description: Integration guide for @daveyplate/better-auth-tauri - cookie-based auth in Tauri v2 desktop apps via deep links. Use when setting up Better Auth in a Tauri application, configuring social OAuth for desktop, or wiring up deep link authentication flows. --- # Better Auth Tauri Plugin - Setup Guide **Package**: `@daveyplate/better-auth-tauri` (v0.1.6+) **Purpose**: Enables cookie-based authentication in Tauri v2 desktop apps using deep links for OAuth callback flows. --- ## Architecture Overview The plugin works in two halves: a **server plugin** (Better Auth middleware) and a **client setup** (Tauri deep link listener). Social OAuth opens in the user's default browser, completes there, then deep-links back into the Tauri app to finalize the session. ### Complete Social Auth Flow ``` 1. User clicks "Sign in with Google" in Tauri app 2. signInSocial() sends request to /api/auth/sign-in/social with Platform header 3. Server middleware appends scheme callback to OAuth redirectURI: → /api/auth/callback/google?callbackURL=my-app:// 4. Server returns Google OAuth URL; client opens it in default browser 5. User authenticates in browser; Google redirects to callback URL 6. Server middleware intercepts callbackURL with scheme prefix 7. Server redirects to /api/auth/callback/success?redirectTo=my-app://api/auth/callback/google?... 8. Success page HTML triggers: window.location.href = 'my-app://...' 9. OS deep link activates Tauri app 10. Client handleAuthDeepLink() calls authClient.$fetch() to process callback 11. Server validates OAuth code, creates session, sets cookie 12. onSuccess callback fires - auth complete ``` --- ## Prerequisites ### Required Tauri Plugins (peer dependencies) ```bash pnpm add @tauri-apps/api @tauri-apps/plugin-deep-link @tauri-apps/plugin-http @tauri-apps/plugin-os @tauri-apps/plugin-opener better-auth ``` | Plugin | Min Version | Purpose | |--------|-------------|---------| | `@tauri-apps/api` | >=2.5.0 | Core Tauri API, `isTauri()` check | | `@tauri-apps/plugin-deep-link` | >=2.2.1 | URL scheme handling (`onOpenUrl`) | | `@tauri-apps/plugin-http` | >=2.4.3 | HTTP with cookie support (macOS fix) | | `@tauri-apps/plugin-os` | >=2.2.1 | Platform detection | | `@tauri-apps/plugin-opener` | >=2.2.6 | Open OAuth URLs in default browser | | `better-auth` | >=1.2.7 | Authentication framework | ### Tauri Deep Link Config In `tauri.conf.json`: ```json { "plugins": { "deep-link": { "desktop": { "schemes": ["my-app"] } } } } ``` --- ## Server Setup ### Plugin Registration (auth.ts) ```typescript import { betterAuth } from "better-auth" import { tauri } from "@daveyplate/better-auth-tauri/plugin" export const auth = betterAuth({ // ... your existing config plugins: [ tauri({ scheme: "my-app", // Must match tauri.conf.json and client callbackURL: "/", // Where to redirect after auth (default: "/") successText: "Authentication successful! You can close this window.", successURL: undefined, // Custom success page URL (gets ?redirectTo param) debugLogs: false, // Enable server-side debug logging }), ], }) ``` ### Plugin Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `scheme` | `string` | **required** | Deep link scheme (without `://`) | | `callbackURL` | `string` | `"/"` | Post-auth redirect path | | `successText` | `string` | Generic message | Text shown on browser success page | | `successURL` | `string` | `undefined` | Custom success page URL (receives `?redirectTo=`) | | `debugLogs` | `boolean` | `false` | Log middleware activity to console | ### What the Server Plugin Does The plugin registers: 1. **Before-hook middleware** on all routes (except `/reset-password` and `/callback/success`): - `appendCallbackURL()`: On `/sign-in/social` requests with a `Platform` header (non-mobile), modifies each social provider's `redirectURI` to include `?callbackURL=scheme://` - `checkCallbackURL()`: On any request where `callbackURL` query param starts with `scheme://`, strips the scheme and redirects to the success page with the deep link URL encoded in `?redirectTo=` 2. **Endpoint** `/callback/success`: Returns HTML success page with embedded `` to trigger the OS deep link --- ## Client Setup ### Auth Client with macOS Cookie Fix **Critical**: macOS production builds require `@tauri-apps/plugin-http` for cookies to work. ```typescript // lib/auth-client.ts import { isTauri } from "@tauri-apps/api/core" import { fetch as tauriFetch } from "@tauri-apps/plugin-http" import { platform } from "@tauri-apps/plugin-os" import { createAuthClient } from "better-auth/react" // or "better-auth/client" export const authClient = createAuthClient({ fetchOptions: { customFetchImpl: (...params) => isTauri() && platform() === "macos" && window.location.protocol === "tauri:" ? tauriFetch(...params) : fetch(...params) } }) ``` ### Standard JS/TS Setup ```typescript import { setupBetterAuthTauri } from "@daveyplate/better-auth-tauri" import { authClient } from "./lib/auth-client" const cleanup = setupBetterAuthTauri({ authClient, scheme: "my-app", // Must match server config debugLogs: false, mainWindowLabel: "main", // Tauri window label (default: "main") onRequest: (href) => { console.log("Processing auth callback:", href) }, onSuccess: (callbackURL) => { window.location.href = callbackURL || "/" }, onError: (error) => { // error: { status: number, statusText: string, code?: string, message?: string } console.error("Auth failed:", error.status, error.statusText) }, }) // Call cleanup() when done (e.g., component unmount) ``` ### React Setup ```tsx import { useBetterAuthTauri } from "@daveyplate/better-auth-tauri/react" import { authClient } from "./lib/auth-client" function App() { useBetterAuthTauri({ authClient, scheme: "my-app", onSuccess: (callbackURL) => { navigate(callbackURL || "/") }, onError: (error) => { toast.error(`Auth failed: ${error.statusText}`) }, }) return } ``` ### Svelte Setup ```svelte ``` --- ## Social Sign-In Social auth opens in the user's default browser (reuses logged-in sessions). Use the provided helper: ```tsx import { signInSocial } from "@daveyplate/better-auth-tauri" import { authClient } from "./lib/auth-client" ``` ### What signInSocial Does 1. Checks if Opener plugin is available (`isTauri()` + correct protocol) 2. Sends sign-in request with `Platform` header (triggers server-side callback URL appending) 3. Sets `disableRedirect: true` to prevent in-app redirect 4. Opens returned OAuth URL in default browser via `openUrl()` 5. Supports `fetchOptions.throw: true` for exception-based error handling ### Non-Social Auth (Magic Link, Email OTP) Works via the `callbackURL` plugin option. The email link contains the deep link scheme directly. No special client-side helper needed - just configure `scheme` in the server plugin and the link in the email will deep-link back to the app. --- ## Package Exports ``` @daveyplate/better-auth-tauri → setupBetterAuthTauri, signInSocial, handleAuthDeepLink @daveyplate/better-auth-tauri/react → useBetterAuthTauri (React hook) @daveyplate/better-auth-tauri/plugin → tauri (server plugin factory) ``` --- ## Quick Checklist - [ ] Install all 5 Tauri plugin peer dependencies - [ ] Register deep link scheme in `tauri.conf.json` - [ ] Add `tauri()` plugin to server `betterAuth()` config with matching scheme - [ ] Configure `customFetchImpl` in auth client for macOS cookies - [ ] Call `setupBetterAuthTauri()` (or `useBetterAuthTauri`) in app entry point - [ ] Use `signInSocial()` helper for social providers (not `authClient.signIn.social()` directly) - [ ] Ensure server has a root route handler (`GET /`) to avoid 404 on post-auth redirect - [ ] Scheme must be identical across: `tauri.conf.json`, server plugin, and client setup --- ## Related Skills - **[sawy-better-auth-ui-tauri-repro](/Users/arthrod/.claude/skills/sawy-better-auth-ui-tauri-repro/SKILL.md)**: Reproduction and fix for the `@daveyplate/better-auth-ui` module-load-time crash in non-HTTP environments (`BetterAuthError: Invalid base URL: tauri://localhost`). Covers pnpm patching, upstream fix proposals, and diagnostic tooling. - **[better-auth-tauri-pitfalls](/Users/arthrod/.claude/skills/better-auth-tauri-pitfalls/SKILL.md)**: Debugging guide covering 10 known pitfalls — 404 after OAuth, macOS deep links, cookie persistence, scheme mismatches, and more. ## See also (related skills — Better Auth family) If your issue relates to: - **Better Auth integration overview** — check `better-auth` if appropriate. - **best-practices guide** — check `better-auth-best-practices` if appropriate. - **create the auth layer (initial scaffolding)** — check `better-auth-create-auth` if appropriate. - **email/password, password reset, verification policies** — check `better-auth-email-password` if appropriate. - **explain a specific error code + provide fix** — check `better-auth-explain-error` if appropriate. - **organization/team plugin** — check `better-auth-organization` if appropriate. - **OAuth/email/magic-link/social provider config** — check `better-auth-providers` if appropriate. - **rate limit, CSRF, trusted origins, secrets, OAuth security** — check `better-auth-security` if appropriate. - **twoFactor plugin enforcement** — check `better-auth-two-factor` if appropriate. - **Tauri-specific gotchas (cookies, deep links, macOS, 404 callbacks)** — check `better-auth-tauri-pitfalls` if appropriate. - **reproduction guide for the better-auth-ui crash on Tauri v2** — check `sawy-better-auth-ui-tauri-repro` if appropriate.