Skip to content

secondsky/claude-skills / plugins/better-auth/skills/better-auth

better-auth

Verified

Skill for integrating Better Auth - comprehensive TypeScript authentication framework for Cloudflare D1, Next.js, Nuxt, and 15+ frameworks. Use when adding auth, encountering D1 adapter errors, or implementing OAuth/2FA/RBAC features.

FileKindSize
SKILL.mdskill md29.2 KB
assets/auth-flow-diagram.mdmarkdown24.0 KB
references/advanced-features.mdmarkdown14.7 KB
references/cloudflare-worker-drizzle.tsscript12.7 KB
references/cloudflare-worker-kysely.tsscript9.7 KB
references/configuration-guide.mdmarkdown10.7 KB
references/database-schema.tsscript10.8 KB
references/databases/mongodb.mdmarkdown5.3 KB
references/databases/mysql.mdmarkdown6.8 KB
references/databases/postgresql.mdmarkdown8.4 KB
references/error-catalog.mdmarkdown12.9 KB
references/framework-comparison.mdmarkdown8.2 KB
references/frameworks/api-frameworks.mdmarkdown9.2 KB
references/frameworks/expo-mobile.mdmarkdown8.7 KB
references/frameworks/nextjs.mdmarkdown5.4 KB
references/frameworks/nuxt.mdmarkdown6.0 KB
references/frameworks/remix.mdmarkdown6.1 KB
references/frameworks/sveltekit.mdmarkdown6.3 KB
references/integrations/electron.mdmarkdown8.2 KB
references/migration-guide-1.4.0.mdmarkdown23.2 KB
references/migration-guide-1.5.0.mdmarkdown6.3 KB
references/nextjs/README.mdmarkdown1.1 KB
references/nextjs/postgres-example.tsscript4.0 KB
references/plugins/api-tokens.mdmarkdown10.0 KB
references/plugins/authentication.mdmarkdown9.2 KB
references/plugins/enterprise.mdmarkdown9.1 KB
references/plugins/payments.mdmarkdown8.0 KB
references/plugins/sso.mdmarkdown9.4 KB
references/plugins/test-utils.mdmarkdown5.5 KB
references/react-client-hooks.tsxother12.8 KB
references/setup-guide.mdmarkdown8.9 KB
references/v1.4-features.mdmarkdown8.2 KB
references/v1.5-features.mdmarkdown11.0 KB
references/v1.6-features.mdmarkdown6.1 KB
scripts/generate-secret.shexecutablescript2.0 KB
scripts/setup-d1-drizzle.shexecutablescript10.2 KB
scripts/test-auth-health.shexecutablescript2.1 KB
scripts/validate-config.tsscript4.3 KB

references/integrations/electron.md

View on GitHub
# better-auth Electron Integration

Full desktop authentication support for Electron apps via system browser OAuth flows.

---

## Installation

```bash
npm install better-auth @better-auth/electron
```

Supports two major versions behind the latest stable Electron release.

---

## Server Setup

Add the Electron plugin to the Better Auth server:

```typescript
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!,
        },
    },
});
```

---

## Web Frontend (Proxy Client)

Handle redirects back into the Electron app:

```typescript
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" },
        }),
    ],
});
```

### Sign-In Page with Electron Redirect

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

function SignIn({ searchParams }) {
    const query = use(searchParams);

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

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

---

## Electron Client Setup

### Main Process Auth Client

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

export const authClient = createAuthClient({
    baseURL: "http://localhost:8081",
    plugins: [
        electronClient({
            signInURL: "https://app.example.com/sign-in",
            protocol: { scheme: "com.example.app" },
            storage: {
                getItem: async (key) => { /* read from storage */ },
                setItem: async (key, value) => { /* write to storage */ },
            },
        }),
    ],
});
```

### Default Storage (using `conf` package)

```bash
npm install conf
```

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

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

---

## Protocol and Trusted Origins

Register protocol scheme in build config:

```javascript
// electron-forge
module.exports = {
    packagerConfig: {
        protocols: [{
            name: "MyApp Protocol",
            schemes: ["com.example.app"],
        }],
    },
};
```

Add to server's `trustedOrigins`:

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

---

## BrowserWindow Configuration

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

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

For sandbox mode, ensure `@better-auth/electron` is bundled into preload:

```typescript
// electron.vite.config.ts
export default defineConfig({
    preload: {
        build: {
            externalizeDeps: {
                exclude: ["@better-auth/electron"],
            },
        },
    },
});
```

---

## Main Process Setup

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

// Must be called before app is ready
authClient.setupMain();
```

Registers protocol handler, user image proxy, content security policies, and IPC bridges.

---

## Renderer Process Setup

### Preload Script

```typescript
import { setupRenderer } from "@better-auth/electron/preload";

// Must be called before app is ready
setupRenderer();
```

### Type Inference

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

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

---

## Usage in Renderer

### Authentication

```typescript
function Auth() {
    useEffect(() => {
        const unsubAuth = window.onAuthenticated((user) => {
            console.log("Authenticated:", user);
        });
        const unsubError = window.onAuthError((ctx) => {
            console.error("Auth error:", ctx.message);
        });

        return () => {
            unsubAuth();
            unsubError();
        };
    }, []);

    return (
        <>
            <button onClick={() => window.requestAuth()}>
                Sign in with Browser
            </button>
            <button onClick={() =>
                window.requestAuth({ provider: "google" })
            }>
                Sign in with Google
            </button>
        </>
    );
}
```

### Sign Out

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

### User Updates

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

---

## Manual Token Exchange

Fallback for environments where deep links don't work reliably.

### Web Frontend

```typescript
const authorizationCode = authClient.electron.getAuthorizationCode();
if (authorizationCode) {
    // Display code for user to copy
}
```

### Electron Renderer

```typescript
function ManualCodeEntry() {
    return (
        <input
            type="text"
            placeholder="Paste code here"
            maxLength={32}
            onChange={(e) => {
                if (e.target.value.length === 32) {
                    // requestAuth() must have been called before
                    window.authenticate({ token: e.target.value });
                }
            }}
        />
    );
}
```

Authorization code is a short-lived 32-character string.

---

## User Image Proxy

Avatars proxied through `user-image://` protocol to avoid CSP issues:

```typescript
<img src={user.image} alt="Avatar" />
```

Configure or disable:

```typescript
electronClient({
    userImageProxy: {
        enabled: true,     // default
        maxSize: 1024 * 1024 * 5, // 5MB default
    },
});
```

---

## Custom IPC Bridges

### Main Process Handler

```typescript
import { ipcMain } from "electron";

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

### Preload Bridge

```typescript
import { contextBridge, ipcRenderer } from "electron";

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

### Type Extension

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

---

## Server Plugin Options

| Option | Default | Description |
|--------|---------|-------------|
| `codeExpiresIn` | `300` | Authorization code validity (seconds) |
| `redirectCookieExpiresIn` | `120` | Redirect cookie validity (seconds) |
| `cookiePrefix` | `"better-auth"` | Cookie name prefix |
| `clientID` | `"electron"` | Client identifier |
| `disableOriginOverride` | `false` | Override origin for Electron API routes |

## Client Plugin Options

| Option | Default | Description |
|--------|---------|-------------|
| `signInURL` | Required | URL for authentication page |
| `protocol` | Required | Deep link protocol scheme |
| `callbackPath` | `"/auth/callback"` | Auth redirect path |
| `storage` | File-based | Storage implementation |
| `storagePrefix` | `"better-auth"` | Storage key prefix |
| `cookiePrefix` | `"better-auth"` | Server cookie name filter |
| `channelPrefix` | `"better-auth"` | IPC channel prefix |
| `clientID` | `"electron"` | Client identifier |
| `sanitizeUser` | None | Strip sensitive fields before sending to renderer |
| `userImageProxy` | `{ enabled: true, maxSize: 5MB }` | Avatar proxy config |
| `disableCache` | `false` | Disable local session caching |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall