Better Auth Plugin for Capacitor

0.3.6 · active · verified Wed Apr 22

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.

Common errors

Warnings

Install

Imports

Quickstart

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.

import { withCapacitor } from 'better-auth-capacitor/client';
import { createAuthClient } from 'better-auth/client';
import { isPlatform } from '@ionic/react'; // Assuming Ionic/React context for platform checks

// --- Server-side configuration (example, typically in your Node.js/Edge function backend) ---
// import { betterAuth } from 'better-auth';
// import { capacitor } from 'better-auth-capacitor';
//
// export const auth = betterAuth({
//   // ... your existing Better Auth config
//   plugins: [
//     capacitor({ disableOriginOverride: false }), // Integrate Capacitor server plugin
//   ],
// });

// --- Client-side configuration in your Capacitor/Ionic app ---
// Define your base URL and deep link scheme
const API_BASE_URL = process.env.VITE_API_BASE_URL ?? 'https://api.example.com';
const APP_SCHEME = process.env.VITE_APP_SCHEME ?? 'myapp'; // Your app's custom URL scheme for deep links

// Create the Better Auth client using the withCapacitor wrapper
const authClient = createAuthClient(
  withCapacitor({
    baseURL: API_BASE_URL,
  },
  {
    scheme: APP_SCHEME,
    storagePrefix: 'better-auth',
    // Optional: disableCache will prevent session caching in preferences if set to true
    // disableCache: false,
  })
);

// Example of usage: Sign in with a social provider
async function initiateSocialLogin(provider: string) {
  try {
    await authClient.signIn.social({
      provider,
      // The redirectTo URL should be handled by your deep linking setup
      // and will trigger the callback logic in better-auth-capacitor.
      redirectTo: `${APP_SCHEME}://callback/auth`,
    });
    console.log(`OAuth flow for ${provider} initiated.`);
  } catch (error) {
    console.error(`Error initiating social login for ${provider}:`, error);
  }
}

// Example of getting the bearer token for API requests
import { getCapacitorAuthToken } from 'better-auth-capacitor/client';

async function fetchAuthenticatedData() {
  const token = await getCapacitorAuthToken({
    storagePrefix: 'better-auth',
    cookiePrefix: 'better-auth', // Ensure this matches your server's cookie prefix
  });

  if (token) {
    console.log('Retrieved auth token:', token.substring(0, 10) + '...');
    // Example fetch (replace with your actual API call)
    try {
      const response = await fetch(`${API_BASE_URL}/protected-data`, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      });
      if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
      const data = await response.json();
      console.log('Protected data:', data);
    } catch (error) {
      console.error('Failed to fetch protected data:', error);
    }
  } else {
    console.log('No authentication token found.');
  }
}

// Simulate app launch and a login attempt
console.log('App starting, setting up auth client...');
// In a real app, you'd call initiateSocialLogin on a button click or similar user action
// For demonstration, let's log the client and token retrieval.
console.log('Auth client initialized:', authClient);
// You might want to automatically check session or refresh on app load
// authClient.getSession().then(session => console.log('Current session:', session));

// To run these in a live app:
// setTimeout(() => initiateSocialLogin('google'), 2000);
// setTimeout(fetchAuthenticatedData, 5000);

view raw JSON →