@better-auth-ui/core 1.6.0

package/src/config/auth-config.ts

@@ -0,0 +1,117 @@
+import type { SocialProvider } from "better-auth/social-providers"
+
+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 { AvatarConfig } from "./avatar-config"
+import type { DeleteUserConfig } from "./delete-user-config"
+import type { EmailAndPasswordConfig } from "./email-and-password-config"
+
+/**
+ * Core authentication configuration interface.
+ *
+ * Defines the base structure for authentication settings including paths,
+ * providers, navigation functions, and feature flags.
+ */
+export interface AuthConfig {
+  /**
+   * Appearance/theme configuration
+   * @remarks `AppearanceConfig`
+   * @default { themes: ["system", "light", "dark"] }
+   */
+  appearance: AppearanceConfig
+  /**
+   * Avatar upload, optimization, and deletion configuration.
+   * @remarks `AvatarConfig`
+   * @default { enabled: true, resize: resizeAvatar, size: 256, extension: "png" }
+   */
+  avatar: AvatarConfig
+  /**
+   * Base paths for different application sections
+   * @remarks `BasePaths`
+   */
+  basePaths: BasePaths
+  /**
+   * Base URL for API endpoints (optional)
+   * @default ""
+   */
+  baseURL: string
+  /**
+   * Allow users to delete their account
+   * @remarks `DeleteUserConfig`
+   */
+  deleteUser?: DeleteUserConfig
+  /**
+   * Email and password authentication configuration
+   * @remarks `EmailAndPasswordConfig`
+   */
+  emailAndPassword: EmailAndPasswordConfig
+  /**
+   * Localization strings for UI components
+   * @remarks `Localization`
+   */
+  localization: Localization
+  /** Whether magic link (passwordless) authentication is enabled */
+  magicLink?: boolean
+  /** Whether multi-session support is enabled */
+  multiSession?: boolean
+  /**
+   * Default redirect path after successful authentication
+   * @default "/"
+   */
+  redirectTo: string
+  /**
+   * List of enabled social authentication providers
+   * @remarks `SocialProvider[]`
+   */
+  socialProviders?: SocialProvider[]
+  /**
+   * View path mappings for different authentication views
+   * @remarks `ViewPaths`
+   */
+  viewPaths: ViewPaths
+  /**
+   * Function to navigate to a new path
+   * @param options - Navigation options with href and optional replace flag
+   * @default window.location.href = href (or window.location.replace if replace: true)
+   * @example
+   * // TanStack Router
+   * navigate={navigate}
+   * // Next.js
+   * navigate={({href, replace}) => replace ? router.replace(href) : router.push(href)}
+   */
+  navigate: (options: { to: string; replace?: boolean }) => void
+}
+
+export const defaultAuthConfig: AuthConfig = {
+  appearance: {
+    themes: ["system", "light", "dark"]
+  },
+  avatar: {
+    enabled: true,
+    resize: resizeAvatar,
+    size: 256,
+    extension: "png"
+  },
+  basePaths,
+  baseURL: "",
+  emailAndPassword: {
+    enabled: true,
+    forgotPassword: true,
+    rememberMe: false,
+    minPasswordLength: 8,
+    maxPasswordLength: 128
+  },
+  redirectTo: "/",
+  viewPaths,
+  localization,
+  navigate: ({ to, replace }) => {
+    if (replace) {
+      window.location.replace(to)
+    } else {
+      window.location.href = to
+    }
+  }
+}

package/src/config/avatar-config.ts

@@ -0,0 +1,39 @@
+/**
+ * Configuration options for avatar handling.
+ */
+export type AvatarConfig = {
+  /**
+   * Delete the current avatar (e.g. remove from storage).
+   * Gets called after the user's avatar is updated to null.
+   */
+  delete?: (url: string) => Promise<void>
+  /**
+   * Whether avatar changing is enabled.
+   * @default true
+   */
+  enabled: boolean
+  /**
+   * Output image format.
+   * @default "png"
+   */
+  extension: "png" | "jpg" | "webp" | "inherit"
+  /**
+   * Resize an image file before upload. Overrides the default resize behavior.
+   * @default Resizes to `size` pixels, square-cropped, output as `extension`.
+   */
+  resize: (
+    file: File,
+    size?: number,
+    extension?: "png" | "jpg" | "webp" | "inherit"
+  ) => Promise<File>
+  /**
+   * Max dimension in pixels for the optimized avatar.
+   * @default 256
+   */
+  size: number
+  /**
+   * Upload a file and return the URL where it was stored.
+   * When undefined, the image is base64-encoded and saved directly to `user.image`.
+   */
+  upload?: (file: File) => Promise<string>
+}

package/src/config/delete-user-config.ts

@@ -0,0 +1,14 @@
+/**
+ * Configuration for account deletion in the UI (mirrors server `user.deleteUser` flags).
+ */
+export interface DeleteUserConfig {
+  /**
+   * Whether the delete user feature is enabled.
+   */
+  enabled?: boolean
+  /**
+   * When `true`, matches server `sendDeleteAccountVerification`: deletion starts by sending a
+   * verification email instead of deleting immediately in this request.
+   */
+  sendDeleteAccountVerification?: boolean
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Configuration options for email and password authentication.
+ */
+export type EmailAndPasswordConfig = {
+  /**
+   * Whether email/password authentication is enabled
+   * @default true
+   */
+  enabled: boolean
+  /**
+   * Whether to show a confirm password field on sign-up forms
+   */
+  confirmPassword?: boolean
+  /**
+   * Whether users can reset forgotten passwords
+   * @default true
+   */
+  forgotPassword: boolean
+  /**
+   * Maximum password length
+   * @default 128
+   */
+  maxPasswordLength: number
+  /**
+   * Minimum password length
+   * @default 8
+   */
+  minPasswordLength: number
+  /**
+   * Maximum password length
+   * @default 128
+   */
+  /** Whether to show a "Remember me" checkbox on sign-in forms */
+  rememberMe?: boolean
+  /** Whether email verification is required before account activation */
+  requireEmailVerification?: boolean
+}

package/src/config/index.ts

@@ -0,0 +1,5 @@
+export * from "./appearance-config"
+export * from "./auth-config"
+export * from "./avatar-config"
+export * from "./delete-user-config"
+export * from "./email-and-password-config"

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./config"
+export * from "./lib/base-paths"
+export * from "./lib/localization"
+export * from "./lib/provider-names"
+export * from "./lib/utils"
+export * from "./lib/view-paths"

package/src/lib/base-paths.ts

@@ -0,0 +1,26 @@
+/**
+ * Base path configuration for authentication, settings, and organization routes.
+ */
+export type BasePaths = {
+  /**
+   * Base path for authentication routes
+   * @default "/auth"
+   */
+  auth: string
+  /**
+   * Base path for settings routes
+   * @default "/settings"
+   */
+  settings: string
+  /**
+   * Base path for organization management routes
+   * @default "/organization"
+   */
+  organization: string
+}
+
+export const basePaths: BasePaths = {
+  auth: "/auth",
+  settings: "/settings",
+  organization: "/organization"
+}

package/src/lib/localization.ts

@@ -0,0 +1,259 @@
+export const localization = {
+  auth: {
+    /** @remarks `"Account"` */
+    account: "Account",
+
+    /** @remarks `"Add Account"` */
+    addAccount: "Add Account",
+
+    /** @remarks `"Already have an account?"` */
+    alreadyHaveAnAccount: "Already have an account?",
+
+    /** @remarks `"Confirm password"` */
+    confirmPassword: "Confirm password",
+
+    /** @remarks `"Confirm your password"` */
+    confirmPasswordPlaceholder: "Confirm your password",
+
+    /** @remarks `"Continue with {{provider}}"` */
+    continueWith: "Continue with {{provider}}",
+
+    /** @remarks `"Email"` */
+    email: "Email",
+
+    /** @remarks `"Enter your email"` */
+    emailPlaceholder: "Enter your email",
+
+    /** @remarks `"Forgot Password"` */
+    forgotPassword: "Forgot Password",
+
+    /** @remarks `"Forgot password?"` */
+    forgotPasswordLink: "Forgot password?",
+
+    /** @remarks `"Hide password"` */
+    hidePassword: "Hide password",
+
+    /** @remarks `"Invalid reset password token"` */
+    invalidResetPasswordToken: "Invalid reset password token",
+
+    /** @remarks `"Magic Link"` */
+    magicLink: "Magic Link",
+
+    /** @remarks `"Magic link sent to your email"` */
+    magicLinkSent: "Magic link sent to your email",
+
+    /** @remarks `"Name"` */
+    name: "Name",
+
+    /** @remarks `"Enter your name"` */
+    namePlaceholder: "Enter your name",
+
+    /** @remarks `"Need to create an account?"` */
+    needToCreateAnAccount: "Need to create an account?",
+
+    /** @remarks `"New password"` */
+    newPassword: "New password",
+
+    /** @remarks `"Enter your new password"` */
+    newPasswordPlaceholder: "Enter your new password",
+
+    /** @remarks `"OR"` */
+    or: "OR",
+
+    /** @remarks `"Password"` */
+    password: "Password",
+
+    /** @remarks `"Enter your password"` */
+    passwordPlaceholder: "Enter your password",
+
+    /** @remarks `"Password reset email sent"` */
+    passwordResetEmailSent: "Password reset email sent",
+
+    /** @remarks `"Password reset successfully"` */
+    passwordResetSuccess: "Password reset successfully",
+
+    /** @remarks `"Passwords do not match"` */
+    passwordsDoNotMatch: "Passwords do not match",
+
+    /** @remarks `"Remember me"` */
+    rememberMe: "Remember me",
+
+    /** @remarks `"Remember your password?"` */
+    rememberYourPassword: "Remember your password?",
+
+    /** @remarks `"Resend"` */
+    resend: "Resend",
+
+    /** @remarks `"Reset Password"` */
+    resetPassword: "Reset Password",
+
+    /** @remarks `"Send Magic Link"` */
+    sendMagicLink: "Send Magic Link",
+
+    /** @remarks `"Send reset link"` */
+    sendResetLink: "Send reset link",
+
+    /** @remarks `"Show password"` */
+    showPassword: "Show password",
+
+    /** @remarks `"Sign In"` */
+    signIn: "Sign In",
+
+    /** @remarks `"Sign Out"` */
+    signOut: "Sign Out",
+
+    /** @remarks `"Sign Up"` */
+    signUp: "Sign Up",
+
+    /** @remarks `"Switch Account"` */
+    switchAccount: "Switch Account",
+
+    /** @remarks `"Verification email sent!"` */
+    verificationEmailSent: "Verification email sent!",
+
+    /** @remarks `"Verify your email"` */
+    verifyYourEmail: "Verify your email"
+  },
+  settings: {
+    /** @remarks `"Account"` */
+    account: "Account",
+
+    /** @remarks `"Account unlinked"` */
+    accountUnlinked: "Account unlinked",
+
+    /** @remarks `"Active"` */
+    active: "Active",
+
+    /** @remarks `"Active sessions"` */
+    activeSessions: "Active sessions",
+
+    /** @remarks `"Avatar"` */
+    avatar: "Avatar",
+
+    /** @remarks `"Current session"` */
+    currentSession: "Current session",
+
+    /** @remarks `"Avatar changed successfully"` */
+    avatarChangedSuccess: "Avatar changed successfully",
+
+    /** @remarks `"Avatar deleted successfully"` */
+    avatarDeletedSuccess: "Avatar deleted successfully",
+
+    /** @remarks `"Change avatar"` */
+    changeAvatar: "Change avatar",
+
+    /** @remarks `"Delete avatar"` */
+    deleteAvatar: "Delete avatar",
+
+    /** @remarks `"Link"` */
+    link: "Link",
+
+    /** @remarks `"Linked accounts"` */
+    linkedAccounts: "Linked accounts",
+
+    /** @remarks `"Link your {{provider}} account"` */
+    linkProvider: "Link your {{provider}} account",
+
+    /** @remarks `"Appearance"` */
+    appearance: "Appearance",
+
+    /** @remarks `"Cancel"` */
+    cancel: "Cancel",
+
+    /** @remarks `"Change email"` */
+    changeEmail: "Change email",
+
+    /** @remarks `"Check your email to confirm the change"` */
+    changeEmailSuccess: "Check your email to confirm the change",
+
+    /** @remarks `"Change password"` */
+    changePassword: "Change password",
+
+    /** @remarks `"Password changed successfully"` */
+    changePasswordSuccess: "Password changed successfully",
+
+    /** @remarks `"Current password"` */
+    currentPassword: "Current password",
+
+    /** @remarks `"Enter your current password"` */
+    currentPasswordPlaceholder: "Enter your current password",
+
+    /** @remarks `"Dark"` */
+    dark: "Dark",
+
+    /** @remarks `"Danger zone"` */
+    dangerZone: "Danger zone",
+
+    /** @remarks `"Delete user"` */
+    deleteUser: "Delete user",
+
+    /** @remarks `"Permanently remove your account and all associated data. This cannot be undone."` */
+    deleteUserDescription:
+      "Permanently remove your account and all associated data. This cannot be undone.",
+
+    /** @remarks `"Check your email to confirm account deletion."` */
+    deleteUserVerificationSent: "Check your email to confirm account deletion.",
+
+    /** @remarks `"Your account has been deleted."` */
+    deleteUserSuccess: "Your account has been deleted.",
+
+    /** @remarks `"Light"` */
+    light: "Light",
+
+    /** @remarks `"Manage accounts"` */
+    manageAccounts: "Manage accounts",
+
+    /** @remarks `"Profile"` */
+    profile: "Profile",
+
+    /** @remarks `"Profile updated successfully"` */
+    profileUpdatedSuccess: "Profile updated successfully",
+
+    /** @remarks `"Revoke"` */
+    revoke: "Revoke",
+
+    /** @remarks `"Revoke session"` */
+    revokeSession: "Revoke session",
+
+    /** @remarks `"Session revoked successfully"` */
+    revokeSessionSuccess: "Session revoked successfully",
+
+    /** @remarks `"Save changes"` */
+    saveChanges: "Save changes",
+
+    /** @remarks `"Set password"` */
+    setPassword: "Set password",
+
+    /** @remarks `"You don't have a password yet. Request a reset link to set one up."` */
+    setPasswordDescription:
+      "You don't have a password yet. Request a reset link to set one up.",
+
+    /** @remarks `"Security"` */
+    security: "Security",
+
+    /** @remarks `"Settings"` */
+    settings: "Settings",
+
+    /** @remarks `"System"` */
+    system: "System",
+
+    /** @remarks `"Theme"` */
+    theme: "Theme",
+
+    /** @remarks `"Unlink {{provider}}"` */
+    unlinkProvider: "Unlink {{provider}}",
+
+    /** @remarks `"Update email"` */
+    updateEmail: "Update email",
+
+    /** @remarks `"Update password"` */
+    updatePassword: "Update password",
+
+    /** @remarks `"Upload avatar"` */
+    uploadAvatar: "Upload avatar"
+  }
+}
+
+export type Localization = typeof localization
+export type AuthLocalization = Localization["auth"]
+export type SettingsLocalization = Localization["settings"]

package/src/lib/provider-names.ts

@@ -0,0 +1,55 @@
+import type { SocialProvider } from "better-auth/social-providers"
+
+/**
+ * Mapping of social authentication provider identifiers to their human-readable display names.
+ */
+export const providerNames: Record<SocialProvider, string> = {
+  apple: "Apple",
+  atlassian: "Atlassian",
+  cognito: "Cognito",
+  discord: "Discord",
+  dropbox: "Dropbox",
+  facebook: "Facebook",
+  figma: "Figma",
+  github: "GitHub",
+  gitlab: "GitLab",
+  google: "Google",
+  huggingface: "Hugging Face",
+  kakao: "Kakao",
+  kick: "Kick",
+  line: "LINE",
+  linear: "Linear",
+  linkedin: "LinkedIn",
+  microsoft: "Microsoft",
+  naver: "Naver",
+  notion: "Notion",
+  paybin: "Paybin",
+  paypal: "PayPal",
+  polar: "Polar",
+  railway: "Railway",
+  reddit: "Reddit",
+  roblox: "Roblox",
+  salesforce: "Salesforce",
+  slack: "Slack",
+  spotify: "Spotify",
+  tiktok: "TikTok",
+  twitch: "Twitch",
+  twitter: "X",
+  vercel: "Vercel",
+  vk: "VK",
+  wechat: "WeChat",
+  zoom: "Zoom"
+}
+
+/**
+ * Get the human-readable display name for an authentication provider.
+ *
+ * @param provider - The provider identifier (e.g., "github", "google").
+ * @returns The mapped display name for `provider` if available, otherwise `provider` with its first character capitalized.
+ */
+export function getProviderName(provider: string) {
+  return (
+    providerNames[provider as SocialProvider] ||
+    provider.charAt(0).toUpperCase() + provider.slice(1)
+  )
+}