Release Notes - v2.0.0

🎉 Better Auth UI v2.0 is here! This major release brings powerful organization management and a cleaner API. While there are breaking changes, we've made migration straightforward with clear examples below.

⚠️ Breaking Changes

Component Changes

UserButton - No longer defaults size to "icon". You must explicitly set size="icon" if you want the icon-only variant.
Icon Colors - We are always using color icons now due to Google restrictions & consistency

API Changes

Props Reorganization - All AuthUIProvider props are now logically grouped for better developer experience
Uppercase Constants - All view paths and localization keys now use UPPERCASE naming
Deprecated Props - Old prop names still work with console warnings but will be removed in a future release

✨ What's New

🏢 Full Organization Support

Build multi-tenant applications with ease! The new organization features include:

Organization Management - Create organizations with custom branding (logos, names)
Team Collaboration - Invite members, manage roles, and control permissions
Smart Organization Switching - Seamless context switching between organizations
Built-in Security - Role-based access control out of the box

// Enable organizations in your app
<AuthUIProvider
  authClient={authClient}
  organization={{
    logo: {
      upload: async (file) => {
        // Your upload logic here
        const formData = new FormData()
        formData.append("logo", file)
        const res = await fetch("/api/upload", { 
          method: "POST", 
          body: formData 
        })
        const { url } = await res.json()
        return url
      }
    },
    // Default roles: "member", "admin", "owner" 
    customRoles: ["editor", "viewer"] // Add your own custom roles
  }}
>

🎨 Better Developer Experience

Cleaner API - Props are now logically grouped for better IntelliSense
Improved TypeScript Support - Better type safety throughout
Consistent Naming - All constants now use UPPERCASE for clarity

🚀 Quick Start Migration

1. Update Your View Paths

View path constants are now UPPERCASE when used in your route configuration:

// Before
import { authViewPaths } from "@daveyplate/better-auth-ui/server"

export function generateStaticParams() {
    return Object.values(authViewPaths).map((pathname) => ({ pathname }))
}

// After - same import, but the values are now UPPERCASE
import { authViewPaths } from "@daveyplate/better-auth-ui/server"

export function generateStaticParams() {
    return Object.values(authViewPaths).map((pathname) => ({ pathname }))
    // Returns: ["SIGN_IN", "SIGN_UP", "SETTINGS", ...] instead of ["signIn", "signUp", "settings", ...]
}

2. Update Your AuthUIProvider

Props are now better organized into logical groups:

// Before - flat structure
<AuthUIProvider
  authClient={authClient}
  uploadAvatar={uploadFunction}
  avatarSize={256}
  avatarExtension="webp"
  providers={["github", "google"]}
  otherProviders={["custom-oauth"]}
  signInSocial="optional"
  confirmPassword={true}
  forgotPassword={true}
  passwordValidation={validationRules}
  rememberMe={true}
  username={true}
  signUpFields={["name", "company"]}
  settingsURL="/dashboard/settings"
  settingsFields={["name", "company"]}
  deleteAccountVerification="password"
  apiKeys={true}
>

// After - grouped structure
<AuthUIProvider
  authClient={authClient}
  avatar={{
    upload: uploadFunction,
    size: 256,
    extension: "webp"
  }}
  social={{
    providers: ["github", "google"],
    signIn: "optional"
  }}
  genericOAuth={{
    providers: ["custom-oauth"],
    signIn: customOAuthSignIn // optional custom function
  }}
  credentials={{
    confirmPassword: true,
    forgotPassword: true,
    passwordValidation: validationRules,
    rememberMe: true,
    username: true
  }}
  signUp={{
    fields: ["name", "company"]
  }}
  settings={{
    url: "/dashboard/settings",
    fields: ["name", "company"]
  }}
  deleteUser={{
    verification: "password"
  }}
  apiKey={true} // Note: renamed from apiKeys
>

3. Update Code Using View Path Constants

If you're using the view path constants in your code, update to UPPERCASE:

// Before
const signInUrl = `/auth/${authViewPaths.signIn}`        // Results in "/auth/sign-in"
const settingsUrl = `/auth/${authViewPaths.settings}`    // Results in "/auth/settings"

// After
const signInUrl = `/auth/${authViewPaths.SIGN_IN}`       // Still results in "/auth/sign-in"
const settingsUrl = `/auth/${authViewPaths.SETTINGS}`    // Still results in "/auth/settings"

// Note: The actual URL paths remain kebab-case (sign-in, settings, etc.)
// Only the constant names changed to UPPERCASE

📋 Complete Migration Guide

AuthUIProvider Props Migration

Click to see all prop migrations

Old Prop	New Location	Notes
`uploadAvatar`	`avatar.upload`
`avatarExtension`	`avatar.extension`
`avatarSize`	`avatar.size`
`settingsFields`	`settings.fields`
`settingsURL`	`settings.url`
`deleteAccountVerification`	`deleteUser.verification`
`providers`	`social.providers`
`otherProviders`	`genericOAuth.providers`
`signInSocial`	`social.signIn`
`confirmPassword`	`credentials.confirmPassword`
`forgotPassword`	`credentials.forgotPassword`
`passwordValidation`	`credentials.passwordValidation`
`rememberMe`	`credentials.rememberMe`
`username`	`credentials.username`
`signUpFields`	`signUp.fields`
`apiKeys`	`apiKey`	Renamed from plural to singular
-	`genericOAuth.signIn`	New: Custom OAuth sign-in function
-	`organization`	New: Organization management features

View Paths Migration

All view path constants are now UPPERCASE:

// Old → New
viewPaths.signIn → viewPaths.SIGN_IN
viewPaths.signUp → viewPaths.SIGN_UP
viewPaths.settings → viewPaths.SETTINGS
viewPaths.forgotPassword → viewPaths.FORGOT_PASSWORD
// ... and so on

Localization Keys Migration

If you're using custom localization, update your keys to UPPERCASE:

// Before
localization={{
  email: "Email Address",
  password: "Password",
  signIn: "Sign In"
}}

// After
localization={{
  EMAIL: "Email Address",
  PASSWORD: "Password",
  SIGN_IN: "Sign In"
}}

🎯 Real-World Examples

Enable Organizations

// Basic setup (includes default roles: member, admin, owner)
<AuthUIProvider
  authClient={authClient}
  organization={true}
>

// Advanced setup with custom roles and logo upload
<AuthUIProvider
  authClient={authClient}
  organization={{
    logo: {
      upload: async (file) => {
        // Your upload logic
        const formData = new FormData()
        formData.append("logo", file)
        const res = await fetch("/api/upload-logo", { 
          method: "POST", 
          body: formData 
        })
        const { url } = await res.json()
        return url
      },
      size: 256
    },
    // Keep default roles and add custom ones
    customRoles: ["editor", "viewer", "moderator"]
  }}
>

Configure Authentication

<AuthUIProvider
  authClient={authClient}
  // Social login configuration
  social={{
    providers: ["github", "google", "discord"],
    signIn: "optional" // or "required"
  }}
  // Password requirements
  credentials={{
    passwordValidation: {
      minLength: 8,
      requireUppercase: true,
      requireNumbers: true
    },
    confirmPassword: true
  }}
  // Sign up customization
  signUp={{
    fields: ["name", "company", "role"]
  }}
>

💡 Pro Tips

Deprecation Warnings - The old props still work but show console warnings. Update at your own pace! They will be removed in a future update.
UserButton Size - Remember to explicitly set size="icon" if you were relying on the default icon-only behavior.

🔄 Component Updates

UserButton

The <UserButton> component no longer defaults to icon size:

// Before - automatically rendered as icon
<UserButton />

// After - specify size explicitly
<UserButton size="icon" />  // For icon-only
<UserButton size="sm" />    // For small button with name
<UserButton />              // Default size with name

🆘 Need Help?

Check out our documentation

🐛 Bug Fixes & Improvements

Fixed passkey icon (now shows fingerprint instead of key)
Improved mobile responsive design for settings
Better error handling throughout
Enhanced TypeScript support with better prop grouping
Improved theme-based icon coloring system

Thank you for using Better Auth UI! We're excited to see what you build with these new features. 🚀

daveyplate/better-auth-ui v2.0.0 on GitHub