Skip to content

Update better-auth skill to v1.6.0 (D1 native, Electron, i18n, OpenTelemetry, SSO)#58

Merged
secondsky merged 2 commits intomainfrom
update/better-auth-v1.6
Apr 8, 2026
Merged

Update better-auth skill to v1.6.0 (D1 native, Electron, i18n, OpenTelemetry, SSO)#58
secondsky merged 2 commits intomainfrom
update/better-auth-v1.6

Conversation

@secondsky
Copy link
Copy Markdown
Owner

@secondsky secondsky commented Apr 8, 2026

Summary

  • Update better-auth skill from package version 1.4.9 to 1.6.0, covering all v1.5 and v1.6 features
  • Add 6 new reference files and update 5 existing ones with production-tested content from official docs
  • Bump collection version to 3.2.2, plugin version to 3.1.0

New Reference Files (6)

File Content
references/v1.5-features.md New CLI, MCP auth, OAuth 2.1 Provider, Electron, i18n, D1 native, secret rotation, seat billing, adapter extraction, typed error codes
references/v1.6-features.md OpenTelemetry, passkey pre-auth, case-insensitive queries, non-blocking scrypt, release tracks
references/migration-guide-1.5.0.md v1.5 breaking changes: API Key moved, after hooks post-transaction, InferUser removed, core/utils split
references/plugins/test-utils.md Testing helpers: factories, DB helpers, auth helpers, OTP capture, Vitest/Playwright examples
references/plugins/sso.md Production SSO: OIDC discovery, SAML SLO, domain verification, organization provisioning, security hardening
references/integrations/electron.md Electron desktop auth: system browser OAuth, IPC bridges, deep links, manual token exchange

Updated Reference Files (5)

  • v1.4-features.md — Fixed OAuth 2.1 plugin (was wrong package), SSO imports to @better-auth/sso, CLI commands to npx auth, SSO config structure
  • plugins/authentication.md — Updated passkey to @better-auth/passkey, added pre-auth registration (v1.6), WebAuthn extensions
  • plugins/enterprise.md — Updated SSO to @better-auth/sso, added SAML SLO, InResponseTo default ON
  • plugins/api-tokens.md — Updated to @better-auth/api-key, added org-owned API keys, multi-configuration
  • configuration-guide.md — Added dynamic base URL, secret key rotation, D1 native, better-auth/minimal, defer session refresh

SKILL.md Changes

  • Bumped package_version from 1.4.9 to 1.6.0
  • Added v1.5 and v1.6 breaking changes and feature highlights
  • Added D1 native support (pass D1 binding directly, no adapter needed)
  • Updated CLI commands to npx auth syntax throughout
  • Added 6 new "When to Load References" entries
  • Updated dependencies with new packages
  • 17 files changed, 2586 insertions, 240 deletions

Test Plan

  • JSON schema validation passed (marketplace.json, plugin.json)
  • SKILL.md frontmatter validation passed
  • All version numbers consistent (plugin 3.1.0, collection 3.2.2)
  • No duplicate content between SKILL.md and references
  • All new reference files follow existing patterns

Summary by CodeRabbit

  • New Features

    • Electron desktop authentication support
    • D1 native database integration
    • Passkey pre-authentication flows
    • OpenTelemetry observability
    • Internationalization support
    • Test utilities for integration/E2E testing
    • Non-destructive secret key rotation
    • Dynamic base URL allowlisting and advanced session controls
  • Documentation

    • Comprehensive migration and upgrade guides (v1.5/v1.6)
    • Expanded integration, CLI, plugin, and reference docs (SSO, API keys, passkeys, Electron, test-utils)
  • Chores

    • Release metadata updated to v3.2.2 and better-auth listings refreshed.

- Add 6 new reference files: v1.5-features, v1.6-features, migration-guide-1.5.0, plugins/sso, plugins/test-utils, integrations/electron
- Update 5 existing references: authentication (passkey pre-auth), enterprise (SSO), api-tokens (new package), configuration (dynamic base URL), v1.4-features (fix inaccuracies)
- Update SKILL.md with v1.5/v1.6 breaking changes, D1 native support, new CLI, new packages
- Bump plugin version to 3.1.0, package version to 1.6.0
- Update CHANGELOG.md, root README.md, marketplace.json to v3.2.2
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 8, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7d25bc86-39ad-43ff-841f-f6bc924f85d9

📥 Commits

Reviewing files that changed from the base of the PR and between 2e4f739 and 71e97e1.

📒 Files selected for processing (8)
  • PACKAGE_VERSION_AUDIT.md
  • plugins/better-auth/README.md
  • plugins/better-auth/skills/better-auth/references/configuration-guide.md
  • plugins/better-auth/skills/better-auth/references/plugins/api-tokens.md
  • plugins/better-auth/skills/better-auth/references/plugins/authentication.md
  • plugins/better-auth/skills/better-auth/references/plugins/enterprise.md
  • plugins/better-auth/skills/better-auth/references/v1.4-features.md
  • plugins/better-auth/skills/better-auth/references/v1.5-features.md

Walkthrough

Marketplace and plugin metadata versions bumped (marketplace → 3.2.2, better-auth plugin → 3.1.0). Changelog and README dates updated. Extensive documentation and reference materials for better-auth (v1.5.x → v1.6.0) added or revised, including migration, configuration, integrations (Electron, SSO), and new plugin docs.

Changes

Cohort / File(s) Summary
Marketplace & Plugin Manifests
\.claude-plugin/marketplace.json, plugins/better-auth/.claude-plugin/plugin.json
Bumped marketplace metadata version 3.0.0 → 3.2.2 and better-auth plugin version 3.0.0 → 3.1.0.
Changelog & README
CHANGELOG.md, README.md
Added v3.2.2 changelog entry (2026-04-08) documenting better-auth upgrade to v1.6.0 and related package/plugin notes; updated README version/date metadata.
Plugin Root Docs & SKILL
plugins/better-auth/README.md, plugins/better-auth/skills/better-auth/SKILL.md
Updated to target better-auth v1.6.0: D1 native guidance, CLI migration to npx auth, v1.5/v1.6 breaking changes, expanded features, updated error/reference counts and metadata.
Configuration & Migration
plugins/better-auth/skills/better-auth/references/configuration-guide.md, .../migration-guide-1.5.0.md
Configuration guide updated for v1.6.0 (baseURL wildcards, secret rotation, session.deferSessionRefresh, secondary verification storage, D1 native usage); added migration guide for v1.4.x → v1.5.0 detailing breaking changes and upgrade steps.
Auth & Token Plugin Docs
.../references/plugins/authentication.md, .../references/plugins/api-tokens.md
Passkey docs updated for v1.6 pre-auth flows and WebAuthn; API key docs reflect extraction to @better-auth/api-key and add org/multi-config usage patterns.
SSO / Enterprise
.../references/plugins/enterprise.md, .../references/plugins/sso.md
Reworked SSO/SAML docs to use @better-auth/sso, added OIDC provider registration patterns, InResponseTo validation defaults, clockSkew option, provisioning hooks, DNS verification, and comprehensive SSO examples.
Integrations & Test Utilities
.../references/integrations/electron.md, .../references/plugins/test-utils.md
Added Electron integration guide (end-to-end desktop auth, IPC/preload patterns) and test-utils docs (factories, helpers, OTP capture, Vitest/Playwright examples).
Feature Reference Pages
.../references/v1.4-features.md, .../v1.5-features.md, .../v1.6-features.md
Refactored v1.4 features and added v1.5/v1.6 feature pages: CLI changes, D1 native support, adapter extraction, secret rotation, OpenTelemetry, passkey pre-auth, adapter query options, and listed breaking behaviors.
Package Audit
PACKAGE_VERSION_AUDIT.md
New automated-style audit across package.json files documenting outdated pins, critical issues, and a decisions-needed summary.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~35 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately and concisely summarizes the main change: updating the better-auth skill to v1.6.0, with specific highlights of major new features (D1 native, Electron, i18n, OpenTelemetry, SSO).
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch update/better-auth-v1.6

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (5)
plugins/better-auth/skills/better-auth/references/plugins/enterprise.md (2)

405-407: ⚠️ Potential issue | 🟡 Minor

Update the troubleshooting note to use clockSkew instead of clockSkewTolerance.

The SSO examples in sso.md and the code sample in enterprise.md (line 147) use clockSkew, but the troubleshooting note at line 406 still references clockSkewTolerance. Update line 406 to:

  • Use clockSkew option to allow for time drift (measured in milliseconds)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/plugins/enterprise.md`
around lines 405 - 407, The troubleshooting note references the deprecated
option clockSkewTolerance; update that line to reference clockSkew instead and
add the units note. Replace "Use `clockSkewTolerance` option to allow for time
drift" with "Use `clockSkew` option to allow for time drift (measured in
milliseconds)" so it matches the SSO examples in sso.md and the code sample in
enterprise.md that already use clockSkew.

361-381: ⚠️ Potential issue | 🟠 Major

Update the combined enterprise example to use the new @better-auth/sso package and API.

The "Combining Enterprise Plugins" section (lines 361–381) still imports sso from better-auth/plugins with outdated SAML configuration fields, while the SSO section above (lines 139–151) uses the correct @better-auth/sso package with the new API. This inconsistency will break copy/paste integrations.

Suggested fix
 import { betterAuth } from "better-auth";
-import { organization, sso, scim, admin } from "better-auth/plugins";
+import { organization, scim, admin } from "better-auth/plugins";
+import { sso } from "@better-auth/sso";
 
 export const auth = betterAuth({
   plugins: [
     organization({
       allowUserToCreateOrganization: false,  // Admin-only
       roles: {
         owner: ["*"],
         admin: ["invite", "remove", "update", "manage-sso"],
         member: ["read"],
       },
     }),
     sso({
       saml: {
-        issuer: "https://your-app.com",
-        callbackURL: "/api/auth/sso/callback",
-        clockSkewTolerance: 60,
+        enableSingleLogout: true,
+        enableInResponseToValidation: true,
+        clockSkew: 60 * 1000,
       },
     }),
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/plugins/enterprise.md`
around lines 361 - 381, Replace the legacy sso import and SAML config in the
combined enterprise example: stop importing sso from "better-auth/plugins" and
instead import the new package "@better-auth/sso", and update the sso(...) call
to use the new API shape shown in the SSO section (e.g., use the new config keys
and structure used with the `@better-auth/sso` package). Specifically, keep the
betterAuth(...) and organization(...) usage but change the import for sso and
adapt the sso(...) options to match the new package's API (same naming and
fields as in the SSO example) so the combined example is consistent and
copy/pasteable.
plugins/better-auth/skills/better-auth/references/plugins/api-tokens.md (1)

385-395: ⚠️ Potential issue | 🟠 Major

Update the combined-token example to use the extracted API key package.

The file correctly shows @better-auth/api-key in earlier sections (lines 19, 65), and the documentation explicitly states apiKey was extracted in v1.5.0. However, line 387 in the "Combining Token Plugins" section still imports apiKey from better-auth/plugins, creating contradictory setup instructions that would cause runtime errors.

Suggested doc fix
 import { betterAuth } from "better-auth";
-import { apiKey, bearer, jwt, oidcProvider } from "better-auth/plugins";
+import { bearer, jwt, oidcProvider } from "better-auth/plugins";
+import { apiKey } from "@better-auth/api-key";
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/plugins/api-tokens.md`
around lines 385 - 395, The combined-token example imports apiKey from
better-auth/plugins but apiKey was extracted into a separate package; update the
import to use the extracted package (import apiKey from "@better-auth/api-key")
in the example where betterAuth and plugins (bearer, jwt, oidcProvider) are used
so the example's import list references apiKey from the `@better-auth/api-key`
package instead of better-auth/plugins.
plugins/better-auth/skills/better-auth/references/plugins/authentication.md (1)

398-412: ⚠️ Potential issue | 🟠 Major

Update the combined-plugins example to match the documented passkey package split.

The documentation correctly establishes that the passkey plugin is a separate package (@better-auth/passkey) as of v1.4.0, but the "Combining Plugins" example at lines 398-412 still imports passkey from better-auth/plugins. This conflicts with the documented setup and will cause incorrect behavior if copied.

Required fix
 import { betterAuth } from "better-auth";
 import {
   twoFactor,
-  passkey,
   magicLink,
   emailOTP,
   anonymous
 } from "better-auth/plugins";
+import { passkey } from "@better-auth/passkey";
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/plugins/authentication.md`
around lines 398 - 412, The combined-plugins example imports passkey from the
wrong module; update the import so passkey is imported from the separate package
`@better-auth/passkey` (while keeping twoFactor, magicLink, emailOTP, anonymous
from better-auth/plugins) and ensure the example still uses the passkey symbol
in the betterAuth plugins array (referencing the passkey function/identifier and
the betterAuth and twoFactor symbols to locate the code).
plugins/better-auth/skills/better-auth/SKILL.md (1)

409-659: 🛠️ Refactor suggestion | 🟠 Major

Reduce SKILL.md size below the 500-line hard limit.

The file currently exceeds the repository cap for SKILL.md. Please move additional operational details into reference files and keep SKILL.md as discovery + routing guidance only.

As per coding guidelines, “SKILL.md files must… Keep SKILL.md under 500 lines using progressive disclosure with ‘When to Load References’ section explaining when to load each reference file.”

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/SKILL.md` around lines 409 - 659, The
SKILL.md "## When to Load References" section and the long bundled-resources
lists exceed the 500-line limit; trim SKILL.md to discovery and routing guidance
only by removing in-depth operational content and moving it into the referenced
files (e.g., references/setup-guide.md, references/error-catalog.md,
references/advanced-features.md, references/configuration-guide.md, references/*
framework and plugin files); collapse the long filename lists and duplicate
“Using Bundled Resources”/framework/database/plugin sections so SKILL.md only
contains concise routing triggers and short pointers to the specific reference
files (keep the header "## When to Load References" and one-line bullets
referencing each filename), ensuring SKILL.md stays under 500 lines while full
details live in the referenced files.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@plugins/better-auth/README.md`:
- Around line 80-99: The README shows a mismatch between the "Errors Prevented
(15 Common Issues)" header and the Performance block claiming "10 documented
issues"; open the README.md and reconcile these counts by either updating the
header "Errors Prevented (15 Common Issues)" to the actual number of bullet
items listed or updating the Performance block's "10 documented issues" to match
15 (or vice versa), ensuring both numbers reflect the true count of items;
specifically search for the strings "Errors Prevented (15 Common Issues)" and
the Performance block phrase "10 documented issues" and adjust the numeric
value(s) so both are consistent with the listed items.

In `@plugins/better-auth/skills/better-auth/references/configuration-guide.md`:
- Around line 3-4: Update the verification stamp that still reads "Last verified
... better-auth@1.4.3" so it matches the file header (Last Updated: 2026-04-08
and Package: better-auth@1.6.0): locate the "Last verified" line or any inline
verification note referencing better-auth@1.4.3 and change the version to
better-auth@1.6.0 and the date to 2026-04-08 so the verification metadata is
consistent with the header.

In `@plugins/better-auth/skills/better-auth/references/integrations/electron.md`:
- Around line 21-34: The server config example uses the wrong key: update the
object passed to betterAuth (the exported auth constant) to replace the social
property with socialProviders so OAuth providers are recognized; specifically
modify the config where betterAuth({ plugins: [electron()], emailAndPassword: {
enabled: true }, social: { ... } }) is defined to use socialProviders: { google:
{ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret:
process.env.GOOGLE_CLIENT_SECRET! } } instead.

In `@plugins/better-auth/skills/better-auth/references/plugins/authentication.md`:
- Around line 227-231: The example incorrectly treats
PublicKeyCredential.isConditionalMediationAvailable as a property; change the
useEffect to call the async method and only trigger the autofill when it
resolves true: inside the useEffect (or an async IIFE) await
PublicKeyCredential.isConditionalMediationAvailable() (first guard that the
method exists), and if it returns true then call authClient.signIn.passkey({
autoFill: true }); otherwise do nothing. Ensure you handle the case where the
static method is undefined before calling it to avoid runtime errors.

In `@plugins/better-auth/skills/better-auth/references/v1.4-features.md`:
- Around line 180-201: The file still contains legacy CLI references; search the
document for old patterns like "npx `@better-auth/cli`", "better-auth/cli", or
command invocations such as "auth init", "auth generate", "auth migrate", "auth
upgrade", and replace them with the new unified CLI invocations shown in this
section (e.g., "npx auth init", "npx auth generate", "npx auth migrate", "npx
auth upgrade", and "npx auth generate --adapter drizzle"); ensure every command
example and any prose mentioning the CLI uses "npx auth" consistently and remove
or update any legacy examples or notes to match the v1.5+ CLI.

In `@plugins/better-auth/skills/better-auth/references/v1.5-features.md`:
- Around line 260-262: The fenced code block containing the environment example
BETTER_AUTH_SECRETS="2:new-secret-key,1:old-secret-key" is missing a language
tag; update that fenced block to include a shell/bash language tag (e.g., change
the opening ``` to ```bash) so the block is typed for linters and renderers.

---

Outside diff comments:
In `@plugins/better-auth/skills/better-auth/references/plugins/api-tokens.md`:
- Around line 385-395: The combined-token example imports apiKey from
better-auth/plugins but apiKey was extracted into a separate package; update the
import to use the extracted package (import apiKey from "@better-auth/api-key")
in the example where betterAuth and plugins (bearer, jwt, oidcProvider) are used
so the example's import list references apiKey from the `@better-auth/api-key`
package instead of better-auth/plugins.

In `@plugins/better-auth/skills/better-auth/references/plugins/authentication.md`:
- Around line 398-412: The combined-plugins example imports passkey from the
wrong module; update the import so passkey is imported from the separate package
`@better-auth/passkey` (while keeping twoFactor, magicLink, emailOTP, anonymous
from better-auth/plugins) and ensure the example still uses the passkey symbol
in the betterAuth plugins array (referencing the passkey function/identifier and
the betterAuth and twoFactor symbols to locate the code).

In `@plugins/better-auth/skills/better-auth/references/plugins/enterprise.md`:
- Around line 405-407: The troubleshooting note references the deprecated option
clockSkewTolerance; update that line to reference clockSkew instead and add the
units note. Replace "Use `clockSkewTolerance` option to allow for time drift"
with "Use `clockSkew` option to allow for time drift (measured in milliseconds)"
so it matches the SSO examples in sso.md and the code sample in enterprise.md
that already use clockSkew.
- Around line 361-381: Replace the legacy sso import and SAML config in the
combined enterprise example: stop importing sso from "better-auth/plugins" and
instead import the new package "@better-auth/sso", and update the sso(...) call
to use the new API shape shown in the SSO section (e.g., use the new config keys
and structure used with the `@better-auth/sso` package). Specifically, keep the
betterAuth(...) and organization(...) usage but change the import for sso and
adapt the sso(...) options to match the new package's API (same naming and
fields as in the SSO example) so the combined example is consistent and
copy/pasteable.

In `@plugins/better-auth/skills/better-auth/SKILL.md`:
- Around line 409-659: The SKILL.md "## When to Load References" section and the
long bundled-resources lists exceed the 500-line limit; trim SKILL.md to
discovery and routing guidance only by removing in-depth operational content and
moving it into the referenced files (e.g., references/setup-guide.md,
references/error-catalog.md, references/advanced-features.md,
references/configuration-guide.md, references/* framework and plugin files);
collapse the long filename lists and duplicate “Using Bundled
Resources”/framework/database/plugin sections so SKILL.md only contains concise
routing triggers and short pointers to the specific reference files (keep the
header "## When to Load References" and one-line bullets referencing each
filename), ensuring SKILL.md stays under 500 lines while full details live in
the referenced files.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 39da9684-9a49-4ec2-9f14-a2bd32dd95d8

📥 Commits

Reviewing files that changed from the base of the PR and between 40506e5 and 2e4f739.

📒 Files selected for processing (17)
  • .claude-plugin/marketplace.json
  • CHANGELOG.md
  • README.md
  • plugins/better-auth/.claude-plugin/plugin.json
  • plugins/better-auth/README.md
  • plugins/better-auth/skills/better-auth/SKILL.md
  • plugins/better-auth/skills/better-auth/references/configuration-guide.md
  • plugins/better-auth/skills/better-auth/references/integrations/electron.md
  • plugins/better-auth/skills/better-auth/references/migration-guide-1.5.0.md
  • plugins/better-auth/skills/better-auth/references/plugins/api-tokens.md
  • plugins/better-auth/skills/better-auth/references/plugins/authentication.md
  • plugins/better-auth/skills/better-auth/references/plugins/enterprise.md
  • plugins/better-auth/skills/better-auth/references/plugins/sso.md
  • plugins/better-auth/skills/better-auth/references/plugins/test-utils.md
  • plugins/better-auth/skills/better-auth/references/v1.4-features.md
  • plugins/better-auth/skills/better-auth/references/v1.5-features.md
  • plugins/better-auth/skills/better-auth/references/v1.6-features.md

Comment on lines +21 to +34
```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!,
},
},
});
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

In better-auth v1.6.x server configuration, is the correct key for OAuth providers socialProvidersorsocial? Please provide an official docs link and a minimal valid example.

💡 Result:

Use socialProviders (not social) in better-auth v1.6.x server config for OAuth/social login providers. This is the key shown in the official docs for configuring social OAuth providers. [1][2]

Official docs link (OAuth / social providers):

https://better-auth.com/docs/concepts/oauth

(Options reference also documents socialProviders.) [2]

Minimal valid example:

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});

[1][2]


Change social to socialProviders in the server config.

The example at lines 21-34 uses social as the key, but better-auth's server configuration requires socialProviders for OAuth provider setup. This would cause the Google provider to not be recognized if copied directly.

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

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

See the official better-auth OAuth docs for details.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/integrations/electron.md`
around lines 21 - 34, The server config example uses the wrong key: update the
object passed to betterAuth (the exported auth constant) to replace the social
property with socialProviders so OAuth providers are recognized; specifically
modify the config where betterAuth({ plugins: [electron()], emailAndPassword: {
enabled: true }, social: { ... } }) is defined to use socialProviders: { google:
{ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret:
process.env.GOOGLE_CLIENT_SECRET! } } instead.

Comment on lines +227 to +231
```typescript
useEffect(() => {
if (!PublicKeyCredential.isConditionalMediationAvailable) return;
authClient.signIn.passkey({ autoFill: true });
}, []);
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Is PublicKeyCredential.isConditionalMediationAvailable a function or property, and what is the recommended browser-safe usage pattern?

💡 Result:

PublicKeyCredential.isConditionalMediationAvailable is a function (a static method), i.e. you call it as PublicKeyCredential.isConditionalMediationAvailable() and it returns a Promise. It’s not a boolean “property”, but you do access it as a property when feature-detecting (checking whether the method exists). [1][2]

Recommended browser-safe usage pattern

const supportsConditionalMediation =
  typeof window.PublicKeyCredential?.isConditionalMediationAvailable === 'function' &&
  (await window.PublicKeyCredential.isConditionalMediationAvailable().catch(() => false));

if (supportsConditionalMediation) {
  // Use conditional UI (autofill)
  const cred = await navigator.credentials.get({
    publicKey: requestOptionsFromServer,
    mediation: 'conditional',
    signal: abortController.signal,
  });
} else {
  // Fallback: offer a normal “Sign in with passkey” button / modal WebAuthn flow
  const cred = await navigator.credentials.get({
    publicKey: requestOptionsFromServer,
    // no `mediation: 'conditional'`
    signal: abortController.signal,
  });
}

Why this pattern:

  • Feature-detect the method before calling it (older browsers won’t have it). [1][2]
  • await it (it’s async) and treat rejection as “not available” (e.g., secure-context / RP-ID related failures). [1]
  • Only set mediation: "conditional" after confirming availability, to avoid user-visible errors. [2]

Browser support varies by version, so feature detection is preferred over UA sniffing. [3]

Sources: MDN docs for the static method + example check [1], WebAuthn Level 3 spec IDL + guidance notes [2], Can I use support table [3].


Fix conditional mediation API usage in the passkey autofill example.

At line 229, PublicKeyCredential.isConditionalMediationAvailable is being treated as a property when it's actually a static async method that returns Promise<boolean>. The current check only verifies whether the method exists (always true on supported browsers) rather than confirming conditional mediation is actually available. This causes the passkey autofill to attempt initialization without proper browser capability verification, potentially resulting in errors or failed autofill flows.

Suggested doc fix
 useEffect(() => {
-  if (!PublicKeyCredential.isConditionalMediationAvailable) return;
-  authClient.signIn.passkey({ autoFill: true });
+  if (!window.PublicKeyCredential?.isConditionalMediationAvailable) return;
+  PublicKeyCredential.isConditionalMediationAvailable().then((isAvailable) => {
+    if (!isAvailable) return;
+    authClient.signIn.passkey({ autoFill: true });
+  });
 }, []);
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```typescript
useEffect(() => {
if (!PublicKeyCredential.isConditionalMediationAvailable) return;
authClient.signIn.passkey({ autoFill: true });
}, []);
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/plugins/authentication.md`
around lines 227 - 231, The example incorrectly treats
PublicKeyCredential.isConditionalMediationAvailable as a property; change the
useEffect to call the async method and only trigger the autofill when it
resolves true: inside the useEffect (or an async IIFE) await
PublicKeyCredential.isConditionalMediationAvailable() (first guard that the
method exists), and if it returns true then call authClient.signIn.passkey({
autoFill: true }); otherwise do nothing. Ensure you handle the case where the
static method is undefined before calling it to avoid runtime errors.

Comment on lines +180 to 201
## CLI Tool (v1.4.4, updated in v1.5.0)

# Or use npx
npx better-auth
```
The new `npx auth` CLI replaces `@better-auth/cli`.

### Commands

```bash
# Initialize better-auth in project
better-auth init
# Initialize better-auth in project (v1.5+)
npx auth init

# Generate auth schema
better-auth generate

# Check configuration
better-auth check
npx auth generate

# Start development server
better-auth dev
```
# Run migrations
npx auth migrate

### Directory Detection (v1.4.2)
# Upgrade to latest version (v1.5+)
npx auth upgrade

The CLI automatically detects `/auth` directory for Next.js App Router:

```bash
# Detects src/app/api/auth/[...all]/route.ts
better-auth check
# ✓ Auth route detected at /api/auth
# Generate with specific adapter (v1.5+)
npx auth generate --adapter drizzle
```
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Update remaining legacy command references to match the new CLI section.

This block correctly switches to npx auth, but the same file still references older command patterns later. Please normalize the whole page to one CLI path to prevent migration mistakes.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@plugins/better-auth/skills/better-auth/references/v1.4-features.md` around
lines 180 - 201, The file still contains legacy CLI references; search the
document for old patterns like "npx `@better-auth/cli`", "better-auth/cli", or
command invocations such as "auth init", "auth generate", "auth migrate", "auth
upgrade", and replace them with the new unified CLI invocations shown in this
section (e.g., "npx auth init", "npx auth generate", "npx auth migrate", "npx
auth upgrade", and "npx auth generate --adapter drizzle"); ensure every command
example and any prose mentioning the CLI uses "npx auth" consistently and remove
or update any legacy examples or notes to match the v1.5+ CLI.

@secondsky secondsky merged commit 8e759f1 into main Apr 8, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant