{"id":16711,"library":"better-auth-capacitor","title":"Better Auth Plugin for Capacitor","description":"The `better-auth-capacitor` package provides an offline-first authentication client plugin specifically designed for Capacitor and Ionic mobile applications. It integrates with the broader `better-auth` ecosystem, offering features like persistent session storage via `@capacitor/preferences`, robust OAuth flow support using system browsers and deep link callbacks, and automatic session refreshing when the app regains focus or network connectivity. The current stable version is 0.3.6, with recent releases indicating an active development cadence focusing on features and bug fixes. Key differentiators include its focus on mobile-specific authentication challenges, seamless integration with Capacitor's native capabilities, and utilities for secure token extraction and custom authentication endpoint integration.","status":"active","version":"0.3.6","language":"javascript","source_language":"en","source_url":"https://github.com/productdevbook/better-auth-capacitor","tags":["javascript","better-auth","capacitor","ionic","authentication","oauth","mobile","typescript"],"install":[{"cmd":"npm install better-auth-capacitor","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-capacitor","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-capacitor","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core utilities for the Better Auth client.","package":"@better-auth/core","optional":false},{"reason":"The main Better Auth framework for server-side plugin integration.","package":"better-auth","optional":false},{"reason":"Required for handling app lifecycle events, especially for OAuth deep link callbacks.","package":"@capacitor/app","optional":false},{"reason":"The core Capacitor runtime environment.","package":"@capacitor/core","optional":false},{"reason":"Used for offline-first session caching and persistent storage of authentication tokens.","package":"@capacitor/preferences","optional":false},{"reason":"Optional dependency for the online manager to enable automatic session refresh on connectivity changes.","package":"@capacitor/network","optional":true},{"reason":"Optional dependency for OAuth flows, though its direct use by the plugin has been minimized in recent versions (v0.3.1 removed it from direct pnpm-lock.yaml dependencies).","package":"@capacitor/browser","optional":true}],"imports":[{"note":"This is the recommended client-side wrapper for automatic Capacitor integration, including OAuth handling and disabling default fetch redirect plugins.","wrong":"const withCapacitor = require('better-auth-capacitor/client');","symbol":"withCapacitor","correct":"import { withCapacitor } from 'better-auth-capacitor/client';"},{"note":"This is the server-side plugin to be added to your `better-auth` configuration for Capacitor-specific authorization proxy and origin override.","wrong":"const capacitor = require('better-auth-capacitor');","symbol":"capacitor","correct":"import { capacitor } from 'better-auth-capacitor';"},{"note":"Utility function for retrieving the bearer token from Capacitor's preferences storage, useful for making authenticated API requests outside the `better-auth` client.","wrong":"const getCapacitorAuthToken = require('better-auth-capacitor/client');","symbol":"getCapacitorAuthToken","correct":"import { getCapacitorAuthToken } from 'better-auth-capacitor/client';"},{"note":"Use this function to manually store an authentication token in Capacitor's preferences after a custom authentication flow.","symbol":"setCapacitorAuthToken","correct":"import { setCapacitorAuthToken } from 'better-auth-capacitor/client';"}],"quickstart":{"code":"import { withCapacitor } from 'better-auth-capacitor/client';\nimport { createAuthClient } from 'better-auth/client';\nimport { isPlatform } from '@ionic/react'; // Assuming Ionic/React context for platform checks\n\n// --- Server-side configuration (example, typically in your Node.js/Edge function backend) ---\n// import { betterAuth } from 'better-auth';\n// import { capacitor } from 'better-auth-capacitor';\n//\n// export const auth = betterAuth({\n//   // ... your existing Better Auth config\n//   plugins: [\n//     capacitor({ disableOriginOverride: false }), // Integrate Capacitor server plugin\n//   ],\n// });\n\n// --- Client-side configuration in your Capacitor/Ionic app ---\n// Define your base URL and deep link scheme\nconst API_BASE_URL = process.env.VITE_API_BASE_URL ?? 'https://api.example.com';\nconst APP_SCHEME = process.env.VITE_APP_SCHEME ?? 'myapp'; // Your app's custom URL scheme for deep links\n\n// Create the Better Auth client using the withCapacitor wrapper\nconst authClient = createAuthClient(\n  withCapacitor({\n    baseURL: API_BASE_URL,\n  },\n  {\n    scheme: APP_SCHEME,\n    storagePrefix: 'better-auth',\n    // Optional: disableCache will prevent session caching in preferences if set to true\n    // disableCache: false,\n  })\n);\n\n// Example of usage: Sign in with a social provider\nasync function initiateSocialLogin(provider: string) {\n  try {\n    await authClient.signIn.social({\n      provider,\n      // The redirectTo URL should be handled by your deep linking setup\n      // and will trigger the callback logic in better-auth-capacitor.\n      redirectTo: `${APP_SCHEME}://callback/auth`,\n    });\n    console.log(`OAuth flow for ${provider} initiated.`);\n  } catch (error) {\n    console.error(`Error initiating social login for ${provider}:`, error);\n  }\n}\n\n// Example of getting the bearer token for API requests\nimport { getCapacitorAuthToken } from 'better-auth-capacitor/client';\n\nasync function fetchAuthenticatedData() {\n  const token = await getCapacitorAuthToken({\n    storagePrefix: 'better-auth',\n    cookiePrefix: 'better-auth', // Ensure this matches your server's cookie prefix\n  });\n\n  if (token) {\n    console.log('Retrieved auth token:', token.substring(0, 10) + '...');\n    // Example fetch (replace with your actual API call)\n    try {\n      const response = await fetch(`${API_BASE_URL}/protected-data`, {\n        headers: {\n          Authorization: `Bearer ${token}`,\n        },\n      });\n      if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);\n      const data = await response.json();\n      console.log('Protected data:', data);\n    } catch (error) {\n      console.error('Failed to fetch protected data:', error);\n    }\n  } else {\n    console.log('No authentication token found.');\n  }\n}\n\n// Simulate app launch and a login attempt\nconsole.log('App starting, setting up auth client...');\n// In a real app, you'd call initiateSocialLogin on a button click or similar user action\n// For demonstration, let's log the client and token retrieval.\nconsole.log('Auth client initialized:', authClient);\n// You might want to automatically check session or refresh on app load\n// authClient.getSession().then(session => console.log('Current session:', session));\n\n// To run these in a live app:\n// setTimeout(() => initiateSocialLogin('google'), 2000);\n// setTimeout(fetchAuthenticatedData, 5000);\n","lang":"typescript","description":"This quickstart demonstrates how to set up the `better-auth-capacitor` client using `withCapacitor` for robust authentication, including initiating a social login flow and retrieving the bearer token for subsequent API requests within a Capacitor/Ionic application. It highlights the crucial client-side configuration for deep linking and token management."},"warnings":[{"fix":"Ensure your `capacitor.config.json` includes the necessary `urlSchemes` for deep linking and that the `scheme` option in `withCapacitor` or `capacitorClient` matches your app's scheme (e.g., `myapp://callback`). Configure your `better-auth` server to use these callback URLs.","message":"OAuth flows, particularly social logins, require proper deep linking configuration in your Capacitor app's `capacitor.config.json` and client-side `scheme` option to redirect back to the app after authentication. Without it, the flow may get stuck in the browser.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use the `withCapacitor` wrapper from `better-auth-capacitor/client`. If performing a manual setup, explicitly set `disableDefaultFetchPlugins: isNativePlatform()` when creating your `createAuthClient` instance.","message":"When integrating Better Auth with Capacitor for OAuth, it's critical to disable Better Auth's default fetch redirect plugins on native platforms. The `withCapacitor` wrapper automatically handles this by setting `disableDefaultFetchPlugins: true`. Manual setup requires this configuration to prevent unwanted browser redirects and allow the native auth sheet to take over.","severity":"breaking","affected_versions":">=0.3.4"},{"fix":"Ensure the server-side `better-auth-capacitor` plugin is correctly configured to handle origin overrides for Capacitor native requests. Leverage `getCapacitorAuthToken` for explicit token retrieval and `setCapacitorAuthToken` for manual token storage post-login, rather than relying solely on browser cookie mechanisms.","message":"On native platforms (iOS/Android), the WebView does not share cookies directly with the system browser used for OAuth. `better-auth-capacitor` is designed to handle this by using deep links to pass session tokens back into the app, but rely on Capacitor's native storage (`@capacitor/preferences`) for persistent session management.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install all required peer dependencies and ensure their versions satisfy the ranges specified in `package.json`. For example: `pnpm add better-auth-capacitor @capacitor/preferences @capacitor/app @capacitor/network @better-auth/core better-auth`.","message":"The plugin has peer dependencies on several Capacitor plugins, specifically `@capacitor/app`, `@capacitor/core`, `@capacitor/network`, and `@capacitor/preferences`. Additionally, it depends on `@better-auth/core` and `better-auth` itself. Missing or incompatible versions of these dependencies can lead to runtime errors or unexpected behavior.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that `capacitor.config.json` has `urlSchemes` defined for your app. Ensure the `scheme` option in `withCapacitor` or `capacitorClient` matches this configuration. If using manual setup, confirm `disableDefaultFetchPlugins: isNativePlatform()` is active.","cause":"The Capacitor app's deep linking scheme is misconfigured, or `disableDefaultFetchPlugins` is not correctly set, causing Better Auth's default web redirect plugin to interfere with the native OAuth flow.","error":"OAuth flow fails to complete or redirects to a blank page on mobile."},{"fix":"Check the `storagePrefix` in your `withCapacitor` or `capacitorClient` options and ensure it's consistent. Confirm that `disableCache` is either `false` or omitted if you intend to use caching. Verify `@capacitor/preferences` is installed and functioning correctly.","cause":"The `better-auth-capacitor` client relies on `@capacitor/preferences` for persistent storage. This issue usually indicates that `storagePrefix` is misconfigured or `disableCache` is inadvertently set to `true`.","error":"Authentication token is not persisted across app restarts or after closing the app."},{"fix":"Add `capacitor()` to the `plugins` array of your `betterAuth` server instance. If encountering CORS issues, investigate the `disableOriginOverride` option in the `capacitor()` plugin and ensure your server's CORS settings are compatible with Capacitor's requests.","cause":"The `capacitor()` server plugin is not correctly integrated into your `better-auth` server configuration, or there's a conflict with custom CORS settings.","error":"Server-side errors related to origin override or authorization proxy when using Capacitor."}],"ecosystem":"npm"}