@better-auth-ui/core 1.6.3 → 1.6.4

package/dist/plugins/theme/theme-plugin.d.ts

@@ -0,0 +1,37 @@
+import { ThemeLocalization } from './theme-localization';
+export type ThemePluginOptions = {
+    /**
+     * Override the plugin's default localization strings.
+     * @remarks `ThemeLocalization`
+     */
+    localization?: Partial<ThemeLocalization>;
+    /**
+     * Initial theme value
+     */
+    theme?: string;
+    /**
+     * Function to set the theme.
+     */
+    setTheme: (theme: string) => void;
+    /**
+     * Available theme options
+     * @default ["system", "light", "dark"]
+     */
+    themes?: string[];
+};
+export declare const themePlugin: ((options: ThemePluginOptions) => Omit<{
+    localization: {
+        appearance: string;
+        theme: string;
+        system: string;
+        light: string;
+        dark: string;
+    };
+    theme: string;
+    setTheme: (theme: string) => void;
+    themes: string[];
+}, "id"> & {
+    id: "theme";
+}) & {
+    id: "theme";
+};

package/dist/plugins/theme/theme-plugin.js

@@ -0,0 +1,18 @@
+import { createAuthPlugin as e } from "../../lib/create-auth-plugin.js";
+import { themeLocalization as t } from "./theme-localization.js";
+//#region src/plugins/theme/theme-plugin.ts
+var n = e("theme", (e) => ({
+	localization: {
+		...t,
+		...e.localization
+	},
+	theme: e.theme ?? "system",
+	setTheme: e.setTheme,
+	themes: e.themes ?? [
+		"system",
+		"light",
+		"dark"
+	]
+}));
+//#endregion
+export { n as themePlugin };

package/dist/plugins/username/username-localization.d.ts

@@ -0,0 +1,17 @@
+export declare const usernameLocalization: {
+    /** @remarks `"Username"` */
+    username: string;
+    /** @remarks `"Enter your username"` */
+    usernamePlaceholder: string;
+    /** @remarks `"Enter your username or email"` */
+    usernameOrEmailPlaceholder: string;
+    /** @remarks `"Username is available"` */
+    usernameAvailable: string;
+    /** @remarks `"Username is already taken. Please try another."` */
+    usernameTaken: string;
+    /** @remarks `"Display Username"` */
+    displayUsername: string;
+    /** @remarks `"Enter your display username"` */
+    displayUsernamePlaceholder: string;
+};
+export type UsernameLocalization = typeof usernameLocalization;

package/dist/plugins/username/username-localization.js

@@ -0,0 +1,12 @@
+//#region src/plugins/username/username-localization.ts
+var e = {
+	username: "Username",
+	usernamePlaceholder: "Enter your username",
+	usernameOrEmailPlaceholder: "Enter your username or email",
+	usernameAvailable: "Username is available",
+	usernameTaken: "Username is already taken. Please try another.",
+	displayUsername: "Display Username",
+	displayUsernamePlaceholder: "Enter your display username"
+};
+//#endregion
+export { e as usernameLocalization };

package/dist/plugins/username/username-plugin.d.ts

@@ -0,0 +1,68 @@
+import { UsernameLocalization } from './username-localization';
+export type UsernamePluginOptions = {
+    /**
+     * Whether to use displayUsername for the visible username field in the profile.
+     */
+    displayUsername?: boolean;
+    /**
+     * Whether to check username availability on sign-up and user profile.
+     */
+    isUsernameAvailable?: boolean;
+    /**
+     * Minimum allowed username length.
+     * @default 3
+     */
+    minUsernameLength?: number;
+    /**
+     * Maximum allowed username length.
+     * @default 30
+     */
+    maxUsernameLength?: number;
+    /**
+     * Override the plugin's default localization strings.
+     * @remarks `UsernameLocalization`
+     */
+    localization?: Partial<UsernameLocalization>;
+};
+export declare const usernamePlugin: ((options?: UsernamePluginOptions | undefined) => Omit<{
+    minUsernameLength: number;
+    maxUsernameLength: number;
+    localization: {
+        username: string;
+        usernamePlaceholder: string;
+        usernameOrEmailPlaceholder: string;
+        usernameAvailable: string;
+        usernameTaken: string;
+        displayUsername: string;
+        displayUsernamePlaceholder: string;
+    };
+    additionalFields: ({
+        name: string;
+        type: "string";
+        label: string;
+        placeholder: string;
+        inputType: "input";
+        signUp: "above";
+        required: boolean;
+    } | {
+        name: string;
+        type: "string";
+        label: string;
+        placeholder: string;
+        inputType: "input";
+        signUp: "above";
+        required?: undefined;
+    })[];
+    /**
+     * Whether to use displayUsername for the visible username field in the profile.
+     */
+    displayUsername?: boolean;
+    /**
+     * Whether to check username availability on sign-up and user profile.
+     */
+    isUsernameAvailable?: boolean;
+}, "id"> & {
+    id: "username";
+}) & {
+    id: "username";
+};

package/dist/plugins/username/username-plugin.js

@@ -0,0 +1,33 @@
+import { createAuthPlugin as e } from "../../lib/create-auth-plugin.js";
+import { usernameLocalization as t } from "./username-localization.js";
+//#region src/plugins/username/username-plugin.ts
+var n = e("username", (e = {}) => {
+	let n = e.minUsernameLength ?? 3, r = e.maxUsernameLength ?? 30, i = {
+		...t,
+		...e.localization
+	};
+	return {
+		...e,
+		minUsernameLength: n,
+		maxUsernameLength: r,
+		localization: i,
+		additionalFields: [{
+			name: "username",
+			type: "string",
+			label: i.username,
+			placeholder: i.usernamePlaceholder,
+			inputType: "input",
+			signUp: "above",
+			required: !0
+		}, ...e.displayUsername ? [{
+			name: "displayUsername",
+			type: "string",
+			label: i.displayUsername,
+			placeholder: i.displayUsernamePlaceholder,
+			inputType: "input",
+			signUp: "above"
+		}] : []]
+	};
+});
+//#endregion
+export { n as usernamePlugin };

package/dist/plugins.js

@@ -0,0 +1,15 @@
+import { deleteUserLocalization as e } from "./plugins/delete-user/delete-user-localization.js";
+import { deleteUserPlugin as t } from "./plugins/delete-user/delete-user-plugin.js";
+import { magicLinkLocalization as n } from "./plugins/magic-link/magic-link-localization.js";
+import { magicLinkMutationKeys as r } from "./plugins/magic-link/magic-link-mutation-keys.js";
+import { magicLinkPlugin as i } from "./plugins/magic-link/magic-link-plugin.js";
+import { multiSessionLocalization as a } from "./plugins/multi-session/multi-session-localization.js";
+import { multiSessionPlugin as o } from "./plugins/multi-session/multi-session-plugin.js";
+import { passkeyLocalization as s } from "./plugins/passkey/passkey-localization.js";
+import { passkeyMutationKeys as c } from "./plugins/passkey/passkey-mutation-keys.js";
+import { passkeyPlugin as l } from "./plugins/passkey/passkey-plugin.js";
+import { themeLocalization as u } from "./plugins/theme/theme-localization.js";
+import { themePlugin as d } from "./plugins/theme/theme-plugin.js";
+import { usernameLocalization as f } from "./plugins/username/username-localization.js";
+import { usernamePlugin as p } from "./plugins/username/username-plugin.js";
+export { e as deleteUserLocalization, t as deleteUserPlugin, n as magicLinkLocalization, r as magicLinkMutationKeys, i as magicLinkPlugin, a as multiSessionLocalization, o as multiSessionPlugin, s as passkeyLocalization, c as passkeyMutationKeys, l as passkeyPlugin, u as themeLocalization, d as themePlugin, f as usernameLocalization, p as usernamePlugin };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@better-auth-ui/core",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "type": "module",
   "scripts": {
     "build": "vite build",
-    "dev": "tsc --watch",
+    "dev": "vite build --watch",
     "test": "vitest"
   },
   "files": [
@@ -17,14 +17,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "import": "./dist/plugins.js"
     }
   },
   "devDependencies": {
-    "better-auth": "^1.6.5",
-    "vitest": "^4.1.4"
+    "better-auth": "^1.6.9",
+    "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "better-auth": ">=1.6.5"
+    "better-auth": ">=1.6.9"
   },
   "repository": {
     "type": "git",

package/src/config/additional-fields-config.ts

@@ -0,0 +1,182 @@
+/** Data type of the additional field. */
+export type AdditionalFieldType = "string" | "number" | "boolean" | "date"
+
+/** Runtime value held by an `AdditionalField` (matches `AdditionalFieldType`). */
+export type AdditionalFieldValue = string | number | boolean | Date
+
+/** UI rendering choice. Default is inferred from `AdditionalField.type`. */
+export type AdditionalFieldInputType =
+  | "input"
+  | "textarea"
+  | "number"
+  | "slider"
+  | "switch"
+  | "checkbox"
+  | "select"
+  | "combobox"
+  | "date"
+  | "datetime"
+  | "hidden"
+
+/**
+ * Augmentation target for widening `AdditionalField` slot types
+ * (`label`, `renderProps`, `renderResult`) in UI packages.
+ *
+ * @example
+ * declare module "@better-auth-ui/core" {
+ *   interface AdditionalFieldRegister { label: ReactNode }
+ * }
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmentation target
+export interface AdditionalFieldRegister {}
+
+/** Resolved label type. Defaults to `string`. */
+export type AdditionalFieldLabel = AdditionalFieldRegister extends {
+  label: infer L
+}
+  ? L
+  : string
+
+/** Resolved argument type for `AdditionalField.render`. */
+export type AdditionalFieldRenderProps = AdditionalFieldRegister extends {
+  renderProps: infer P
+}
+  ? P
+  : { name: string; field: AdditionalField; isPending?: boolean }
+
+/** Resolved return type for `AdditionalField.render`. */
+export type AdditionalFieldRenderResult = AdditionalFieldRegister extends {
+  renderResult: infer R
+}
+  ? R
+  : unknown
+
+/** Option for a `select` input. */
+export interface AdditionalFieldOption {
+  label: AdditionalFieldLabel
+  value: string
+}
+
+/** Configuration for a single additional user field. */
+export interface AdditionalField {
+  /** Field name. Used as the user object key and form input `name`. */
+  name: string
+  /** Data type of the field. */
+  type: AdditionalFieldType
+  /** Visible label rendered next to the input. */
+  label: AdditionalFieldLabel
+  /** Override the default UI rendering. @default inferred from `type` */
+  inputType?: AdditionalFieldInputType
+  /** Placeholder text. */
+  placeholder?: string
+  /** Content rendered as a prefix addon inside the input group. */
+  prefix?: AdditionalFieldLabel
+  /** Content rendered as a suffix addon inside the input group. */
+  suffix?: AdditionalFieldLabel
+  /**
+   * `Intl.NumberFormat` options for number fields. Use `maximumFractionDigits`
+   * (and optionally `minimumFractionDigits`) to allow decimals, or `style: "currency"`
+   * / `style: "percent"` for richer formatting.
+   */
+  formatOptions?: Intl.NumberFormatOptions
+  /** Minimum value. Applies to `number` and `slider` input types. */
+  min?: number
+  /** Maximum value. Applies to `number` and `slider` input types. */
+  max?: number
+  /** Step value. Applies to `number` and `slider` input types. */
+  step?: number
+  /** @default false */
+  required?: boolean
+  /**
+   * Default value used to seed the input on the sign-up form. On the user
+   * profile, the value is always re-seeded from the persisted session.
+   */
+  defaultValue?: AdditionalFieldValue | null
+  /**
+   * Render the field but exclude it from submission payloads.
+   * @default false
+   */
+  readOnly?: boolean
+  /**
+   * Show a copy-to-clipboard button as a suffix. Input variant only.
+   * @default false
+   */
+  copyable?: boolean
+  /** Options for the select input type. */
+  options?: AdditionalFieldOption[]
+  /**
+   * Custom client-side validation. Throw an `Error` (the `message` is shown
+   * to the user) when invalid; return / resolve normally when valid.
+   *
+   * Receives the parsed value (after `parseAdditionalFieldValue`).
+   */
+  validate?: (
+    value: AdditionalFieldValue | null | undefined
+  ) => void | Promise<void>
+  /**
+   * Render on the sign-up form. Pass `"above"` to render between the `email`
+   * and `password` fields; otherwise the field renders below the password
+   * block. `true` is an alias for `"below"`.
+   * @default false
+   */
+  signUp?: boolean | "above" | "below"
+  /** Render on the user profile. @default true */
+  profile?: boolean
+  /**
+   * Custom renderer. Replaces the host UI package's built-in input. Must emit
+   * an input named `field.name` so the value is captured by the form's
+   * `FormData`.
+   */
+  render?: (props: AdditionalFieldRenderProps) => AdditionalFieldRenderResult
+}
+
+/** Ordered list of `AdditionalField` configurations. */
+export type AdditionalFields = AdditionalField[]
+
+/**
+ * Convert a raw form value into the JS value Better Auth expects.
+ * Returns `null` for blank input (explicit clear), `undefined` when omitted
+ * or unparseable. Booleans always return `true`/`false`.
+ */
+export function parseAdditionalFieldValue(
+  field: AdditionalField,
+  raw: string | null | undefined
+): AdditionalFieldValue | null | undefined {
+  if (field.type === "boolean") {
+    // FormData: checked checkbox/switch sends "on"; unchecked sends nothing.
+    return raw === "on" || raw === "true"
+  }
+
+  if (raw == null) return undefined
+  if (raw === "") return null
+
+  if (field.type === "number") {
+    const parsed = Number(raw)
+    return Number.isNaN(parsed) ? undefined : parsed
+  }
+
+  if (field.type === "date") {
+    const parsed = new Date(raw)
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed
+  }
+
+  return raw
+}
+
+/** Resolve the effective `inputType`, defaulting based on `field.type`. */
+export function resolveInputType(
+  field: AdditionalField
+): AdditionalFieldInputType {
+  if (field.inputType) return field.inputType
+
+  switch (field.type) {
+    case "number":
+      return "number"
+    case "boolean":
+      return "switch"
+    case "date":
+      return "date"
+    default:
+      return "input"
+  }
+}

package/src/config/auth-config.ts

@@ -1,14 +1,13 @@
 import type { SocialProvider } from "better-auth/social-providers"
 
+import type { AuthPlugin } from "../lib/auth-plugin"
 import { type BasePaths, basePaths } from "../lib/base-paths"
 import { type Localization, localization } from "../lib/localization"
 import { resizeAvatar } from "../lib/utils"
 import { type ViewPaths, viewPaths } from "../lib/view-paths"
-import type { AppearanceConfig } from "./appearance-config"
+import type { AdditionalFields } from "./additional-fields-config"
 import type { AvatarConfig } from "./avatar-config"
-import type { DeleteUserConfig } from "./delete-user-config"
 import type { EmailAndPasswordConfig } from "./email-and-password-config"
-import type { UsernameConfig } from "./username-config"
 
 /**
  * Core authentication configuration interface.
@@ -18,11 +17,10 @@ import type { UsernameConfig } from "./username-config"
  */
 export interface AuthConfig {
   /**
-   * Appearance/theme configuration
-   * @remarks `AppearanceConfig`
-   * @default { themes: ["system", "light", "dark"] }
+   * Additional user fields rendered on sign-up and the user profile.
+   * @remarks `AdditionalFields`
    */
-  appearance: AppearanceConfig
+  additionalFields?: AdditionalFields
   /**
    * Avatar upload, optimization, and deletion configuration.
    * @remarks `AvatarConfig`
@@ -39,11 +37,6 @@ export interface AuthConfig {
    * @default ""
    */
   baseURL: string
-  /**
-   * Allow users to delete their account
-   * @remarks `DeleteUserConfig`
-   */
-  deleteUser?: DeleteUserConfig
   /**
    * Email and password authentication configuration
    * @remarks `EmailAndPasswordConfig`
@@ -54,12 +47,13 @@ export interface AuthConfig {
    * @remarks `Localization`
    */
   localization: Localization
-  /** Whether Magic Link plugin is enabled */
-  magicLink?: boolean
-  /** Whether Multi Session plugin is enabled */
-  multiSession?: boolean
-  /** Whether Passkey plugin is enabled */
-  passkey?: boolean
+  /**
+   * Registered auth plugins. UI packages widen the element type via the
+   * `AuthPluginRegister` module-augmentation slot.
+   * @remarks `AuthPlugin[]`
+   * @default []
+   */
+  plugins: AuthPlugin[]
   /**
    * Default redirect path after successful authentication
    * @default "/"
@@ -75,11 +69,6 @@ export interface AuthConfig {
    * @remarks `ViewPaths`
    */
   viewPaths: ViewPaths
-  /**
-   * Username plugin configuration
-   * @remarks `UsernameConfig`
-   */
-  username: UsernameConfig
   /**
    * Function to navigate to a new path
    * @param options - Navigation options with href and optional replace flag
@@ -94,9 +83,6 @@ export interface AuthConfig {
 }
 
 export const defaultAuthConfig: AuthConfig = {
-  appearance: {
-    themes: ["system", "light", "dark"]
-  },
   avatar: {
     enabled: true,
     resize: resizeAvatar,
@@ -108,20 +94,15 @@ export const defaultAuthConfig: AuthConfig = {
   emailAndPassword: {
     enabled: true,
     forgotPassword: true,
+    name: true,
     rememberMe: false,
     minPasswordLength: 8,
     maxPasswordLength: 128
   },
+  plugins: [],
   redirectTo: "/",
   viewPaths,
   localization,
-  username: {
-    enabled: false,
-    displayUsername: true,
-    isUsernameAvailable: true,
-    minUsernameLength: 3,
-    maxUsernameLength: 30
-  },
   navigate: ({ to, replace }) => {
     if (replace) {
       window.location.replace(to)

package/src/config/email-and-password-config.ts

@@ -27,9 +27,11 @@ export type EmailAndPasswordConfig = {
    */
   minPasswordLength: number
   /**
-   * Maximum password length
-   * @default 128
+   * Whether to render the name field on the sign-up form. When `false`,
+   * sign-up submits with `name: ""`.
+   * @default true
    */
+  name?: boolean
   /** Whether to show a "Remember me" checkbox on sign-in forms */
   rememberMe?: boolean
   /** Whether email verification is required before account activation */

package/src/config/index.ts

@@ -1,6 +1,4 @@
-export * from "./appearance-config"
+export * from "./additional-fields-config"
 export * from "./auth-config"
 export * from "./avatar-config"
-export * from "./delete-user-config"
 export * from "./email-and-password-config"
-export * from "./username-config"

package/src/index.ts

@@ -1,5 +1,10 @@
 export * from "./config"
+export * from "./lib/auth-mutation-keys"
+export * from "./lib/auth-plugin"
+export * from "./lib/auth-query-keys"
 export * from "./lib/base-paths"
+export * from "./lib/create-auth-plugin"
+export * from "./lib/deep-partial"
 export * from "./lib/localization"
 export * from "./lib/provider-names"
 export * from "./lib/utils"

package/src/lib/auth-mutation-keys.ts

@@ -0,0 +1,88 @@
+/**
+ * Hierarchical mutation key factory for every Better Auth mutation managed by
+ * this library.
+ *
+ * Mutation keys are mostly used for `useIsMutating` and global
+ * `MutationCache` observers (e.g. toast handling), so the keys are static
+ * tuples rather than parameterised factories. Each grouping exposes an
+ * `all` prefix so consumers can match a whole feature at once:
+ *
+ * ```ts
+ * useIsMutating({ mutationKey: authMutationKeys.all })
+ * useIsMutating({ mutationKey: authMutationKeys.signIn.all })
+ * useIsMutating({ mutationKey: authMutationKeys.signIn.email })
+ * ```
+ *
+ * This factory lives in `@better-auth-ui/core` so it can be shared across
+ * framework packages (`@better-auth-ui/react`, a future `/solid` package,
+ * etc.) — the mutation cache entries line up regardless of which framework
+ * package the mutation options factory came from.
+ *
+ * For query keys, see `authQueryKeys` in `./auth-query-keys`.
+ */
+export const authMutationKeys = {
+  /** Root key for every Better Auth mutation. */
+  all: ["auth"] as const,
+
+  /** Sign-in mutations, grouped by strategy. */
+  signIn: {
+    /** Prefix matching every sign-in mutation. */
+    all: ["auth", "signIn"] as const,
+    /** Key for `signIn.email`. */
+    email: ["auth", "signIn", "email"] as const,
+    /** Key for `signIn.social`. */
+    social: ["auth", "signIn", "social"] as const,
+    /** Key for `signIn.username`. */
+    username: ["auth", "signIn", "username"] as const
+  },
+
+  /** Sign-up mutations, grouped by strategy. */
+  signUp: {
+    /** Prefix matching every sign-up mutation. */
+    all: ["auth", "signUp"] as const,
+    /** Key for `signUp.email`. */
+    email: ["auth", "signUp", "email"] as const
+  },
+
+  /** Key for `signOut`. */
+  signOut: ["auth", "signOut"] as const,
+
+  /** Key for `requestPasswordReset`. */
+  requestPasswordReset: ["auth", "requestPasswordReset"] as const,
+  /** Key for `resetPassword`. */
+  resetPassword: ["auth", "resetPassword"] as const,
+  /** Key for `sendVerificationEmail`. */
+  sendVerificationEmail: ["auth", "sendVerificationEmail"] as const,
+
+  /** Multi-session mutations. */
+  multiSession: {
+    /** Prefix matching every multi-session mutation. */
+    all: ["auth", "multiSession"] as const,
+    /** Key for `multiSession.revoke`. */
+    revoke: ["auth", "multiSession", "revoke"] as const,
+    /** Key for `multiSession.setActive`. */
+    setActive: ["auth", "multiSession", "setActive"] as const
+  },
+
+  /** Key for `changeEmail`. */
+  changeEmail: ["auth", "changeEmail"] as const,
+  /** Key for `changePassword`. */
+  changePassword: ["auth", "changePassword"] as const,
+  /** Key for `deleteUser`. */
+  deleteUser: ["auth", "deleteUser"] as const,
+  /** Key for `linkSocial`. */
+  linkSocial: ["auth", "linkSocial"] as const,
+  /** Key for `revokeSession`. */
+  revokeSession: ["auth", "revokeSession"] as const,
+  /** Key for `unlinkAccount`. */
+  unlinkAccount: ["auth", "unlinkAccount"] as const,
+  /** Key for `updateUser`. */
+  updateUser: ["auth", "updateUser"] as const,
+
+  /**
+   * Key for `isUsernameAvailable`. This is technically a read, but it's
+   * exposed via better-auth's mutation surface and lives under the mutation
+   * factories for parity with other username flows.
+   */
+  isUsernameAvailable: ["auth", "isUsernameAvailable"] as const
+} as const