Electron Integration

Electron is a popular framework for building cross-platform desktop applications using web technologies.

Better Auth can be integrated into Electron apps to provide secure authentication flows, leveraging the system browser.

Installation

npm install better-auth @better-auth/electron

import { betterAuth } from "better-auth";
import { electron } from "@better-auth/electron";

export const auth = betterAuth({
  plugins: [electron()],
  emailAndPassword: {
    enabled: true,
  },
  social: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});

import { createAuthClient } from "better-auth/client";
import { electronProxyClient } from "@better-auth/electron/proxy";

export const authClient = createAuthClient({
  baseURL: "http://localhost:8081",
  plugins: [
    electronProxyClient({
      protocol: {
        scheme: "com.example.app"
      },
    }),
  ],
});

import { createAuthClient } from "better-auth/client";
import { electronClient } from "@better-auth/electron/client";

export const authClient = createAuthClient({
  baseURL: "http://localhost:8081", // Base URL of your Better Auth frontend
  plugins: [
    electronClient({
      signInURL: "https://app.example.com/sign-in", // The URL to redirect to for authentication
      protocol: {
        scheme: "com.example.app" // The custom protocol scheme registered by your Electron app
      },
      storage: {
        getItem: async (key) => {
          // retrieve entry from storage
        },
        setItem: async (key, value) => {
          // set entry in storage
        },
      },
    }),
  ],
});

npm install conf

import { storage } from "@better-auth/electron/storage";

electronClient({
  storage: storage(),
});

module.exports = {
  packagerConfig: {
    protocols: [{
      name: "MyApp Protocol",
      schemes: ["com.example.app"],
    }],
  },
  // ...other config options
};

{
  "protocols": [
    {
      "name": "MyApp Protocol",
      "schemes": ["com.example.app"]
    }
  ],
  // ...other config options
}

export const auth = betterAuth({
  trustedOrigins: ["com.example.app:/"],
});

import { BrowserWindow } from "electron";
import { join } from "node:path";

const win = new BrowserWindow({
  webPreferences: {
    preload: join(__dirname, "preload.mjs"),
    nodeIntegration: false,
    contextIsolation: true,
  },
});

import { authClient } from "./lib/auth-client";

authClient.setupMain();

import { authClient } from "./lib/auth-client";

authClient.setupRenderer();

import type { authClient } from "./lib/auth-client";

declare global {
  type Bridges = typeof authClient.$Infer.Bridges;
  interface Window extends Bridges {}
}

Usage

Handling Authorization in the Browser

In order to redirect users back to your Electron application, you need to call the ensureElectronRedirect() method on your web sign-in callback page. Also make sure to preserve any PKCE and state parameters during the sign-in initiation, by passing them via fetchOptions.query.

The following example uses React, but the same logic applies to any framework:

import { useEffect, use } from "react";
import { authClient } from "../auth-client";

function SignIn({
  searchParams,
}: {
  searchParams: Promise<{
    client_id?: string | undefined;
    state?: string | undefined;
    code_challenge?: string | undefined;
    code_challenge_method?: string | undefined;
  }>;
}) {
  const query = use(searchParams);

  useEffect(() => {
    const id = authClient.ensureElectronRedirect();
    return () => {
      clearTimeout(id);
    }
  }, []);

  return (
    <button
      onClick={() =>
        authClient.signIn.social({
          provider: "google",
          fetchOptions: { query }, // preserve PKCE/state
        });
      }
    >
      Sign in with Google
    </button>
  );
}

Handling Authentication in Electron

In your Electron renderer process, you can use the IPC bridges exposed by the preload script.

function Auth() {
  useEffect(() => {
    const unsubscribeAuthenticated =
      window.onAuthenticated((user) => {
        console.log("Authenticated user:", user);
      });
    const unsubscribeAuthError =
      window.onAuthError((ctx) => {
        toast.error(`Authentication error: ${ctx.message}`);
      });

    return () => {
      unsubscribeAuthenticated();
      unsubscribeAuthError();
    };
  }, []);

  return (
    <>
      <button onClick={() => window.requestAuth()}>
        Sign in with Browser
      </button>
      <button
        onClick={() =>
          window.requestAuth({
            provider: "google", // sign in with social provider, redirecting directly to the provider
          });
        }
      >
        Sign in with Google
      </button>
    </>
  );
}

In the main process, you can call from the auth client directly:

import { authClient } from "./lib/auth-client";

authClient.requestAuth();

Sign Out

To sign out the user inside the renderer process, you can use the signOut bridge in the renderer process:

<button onClick={() => window.signOut()}>Sign out</button>

Subscribing to User Updates

You can listen for user changes via the onUserUpdated bridge in the renderer process:

useEffect(() => {
  const unsubscribe = window.onUserUpdated((user) => {
    console.log("User updated:", user);
  });
  return () => unsubscribe();
}, []);

Handling Errors

Listen for authentication errors via the onAuthError bridge in the renderer process. The bridge will receive error context forwarded from fetch hooks.

useEffect(() => {
  const unsubscribe = window.onAuthError((ctx) => {
    console.error("Authentication error:", ctx);
  });
  return () => unsubscribe();
}, []);

Creating IPC bridges

You should create IPC bridges to extend the functionality exposed to your renderer process. This ensures a minimal, safe API surface.

First, create an IPC handler in the main process that uses the authClient to perform the desired action:

import { authClient } from "./lib/auth-client";
import { ipcMain } from "electron";

ipcMain.handle("myBridge", async (_event, data) => {
  const cookie = authClient.getCookie();
  return await authClient.someEndpoint({
    data,
    fetchOptions: {
      headers: { cookie },
    },
  });
});

Next, expose the bridge in your preload script using contextBridge:

import { contextBridge, ipcRenderer } from "electron";

contextBridge.exposeInMainWorld("myBridge", (data: Record<string, any>) => {
  return ipcRenderer.invoke("myBridge", data);
});

import type { authClient } from "./lib/auth-client";

declare global {
  type Bridges = typeof authClient.$Infer.Bridges;
  interface Window extends Bridges {
    myBridge: (data: Record<string, any>) => Promise<any>;
  }
}

Now you can call your custom bridge from anywhere in the renderer process:

useEffect(() => {
  window
    .myBridge({
      foo: "bar",
    })
    .then((res) => {
      console.log("Bridge response:", res);
    });
}, []);

For more details, check out Electron's Inter-Process Communication tutorial.

Options

Server plugin

codeExpiresIn?

The duration, in seconds, for which the authorization code is valid. (defaults to 300)

Note that the authorization code will be refreshed during active endpoint usage.

electron({
  codeExpiresIn: 300, // 5 minutes
});

redirectCookieExpiresIn?

The duration, in seconds, for which the redirect cookie remains valid. (defaults to 120)

electron({
  redirectCookieExpiresIn: 120, // 2 minutes
});

The redirect cookie name is derived by the clientID.

cookiePrefix?

The prefix to use for cookies set by the plugin. (defaults to better-auth)

electron({
  cookiePrefix: "better-auth",
});

clientID?

The client id to use for identifying the Electron client during authorization. (defaults to electron)

Make sure this matches the clientID provided to both the proxy and electron client plugin.

electron({
  clientID: "electron",
});

disableOriginOverride?

Override the origin for Electron API routes. (defaults to false)

Enable this if you're facing cors origin issues with Electron API routes.

electron({
  disableOriginOverride: true,
});

Proxy client

protocol

The protocol scheme to use for deep linking in Electron.

Should follow the reverse domain name notation to ensure uniqueness.

Make sure this matches the protocol scheme provided to the Electron client and trustedOrigins.

electronProxyClient({
  protocol: "com.example.app",
});

electronProxyClient({
  protocol: {
    scheme: "com.example.app",
  },
});

callbackPath?

The callback path to use for authentication redirects. (defaults to /auth/callback)

Make sure this matches the path provided to the electron client plugin.

electronProxyClient({
  callbackPath: "/auth/callback",
});

clientID?

The client id to use for identifying the Electron client during authorization. (defaults to electron)

Make sure this matches the clientID provided to both the server and electron client plugin.

electronProxyClient({
  clientID: "electron",
});

cookiePrefix?

The prefix to use for cookies set by the plugin. (defaults to better-auth)

electronProxyClient({
  cookiePrefix: "better-auth",
});

Client plugin

signInURL

The URL to redirect to for authentication.

electronClient({
  signInURL: "http://localhost:3000/sign-in",
});

protocol

The protocol scheme to use for deep linking in Electron.

Should follow the reverse domain name notation to ensure uniqueness.

Make sure this matches the protocol scheme provided to the proxy client and trustedOrigins.

electronProxyClient({
  protocol: "com.example.app",
});

electronProxyClient({
  protocol: {
    scheme: "com.example.app",
  },
});

callbackPath?

The callback path to use for authentication redirects. (defaults to /auth/callback)

Make sure this matches the path provided to the proxy client plugin.

electronClient({
  callbackPath: "/auth/callback",
});

storage

Storage solution to use to store session and cookie data.

By default a storage file is generated in the userData directory. The name is derived by the project name.

electronClient({
  storage: {
    getItem: (key) => {
      // get entry from storage
    },
    setItem: (key, value) => {
      // set entry in storage
    },
  },
});

storagePrefix?

Prefix for local storage keys. (defaults to better-auth)

electronClient({
  storagePrefix: "better-auth",
});

cookiePrefix?

Prefix(es) for server cookie names to filter. (defaults to better-auth)

This is used to identify which cookies belong to better-auth to prevent infinite refetching when third-party cookies are set.

electronClient({
  cookiePrefix: "better-auth",
});

electronClient({
  cookiePrefix: ["better-auth", "my-app"],
});

channelPrefix?

Channel prefix for IPC bridges. (defaults to better-auth)

electronClient({
  channelPrefix: "myapp",
});

clientID?

The client id to use for identifying the Electron client during authorization. (defaults to electron)

Make sure this matches the clientID provided to both the server and proxy client plugin.

electronClient({
  clientID: "electron",
});

disableCache?

Whether to disable caching the session data locally. (defaults to false)

electronClient({
  disableCache: true,
});