v2.0.0

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 - noColorIcons prop has been removed. colorIcons now defaults to undefined for automatic theme-based coloring (colored when light, black & white when dark). You can set it to true or false to force color or no color icons for both themes.

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}
  noColorIcons={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
  colorIcons={false} // Replaces noColorIcons
>

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
noColorIcons	-	Removed. Use colorIcons={false} instead
colorIcons	colorIcons	Now defaults to undefined (auto theme-based)
-	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

1. Deprecation Warnings - The old props still work but show console warnings. Update at your own pace! They will be removed in a future update.
2. 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. 🚀