Username-based accounts
Allow users to register and authenticate without exposing email addresses as their login identifier.
Better Auth · Const
username
The username plugin adds username-based authentication to Better Auth’s email/password flow. It supports username signup, login, updates, availability checks, validation, length limits, and normalization.
How it works
The username plugin extends email/password authentication with username-based sign-in. Add it to the server, generate or run the database migration, and add the client plugin to use username signup, sign-in, updates, and availability checks.
Syntax
username()Key points
- It extends the built-in email/password flow rather than replacing that authenticator.
- Registration continues through signUp.email, with username included in the submitted data.
- Username login uses the dedicated signIn.username client method.
- Authenticated users can change their username through updateUser when mutability is allowed.
- Availability can be checked before registration or a username change.
- The default minimum username length is three characters.
- The default maximum username length is thirty characters.
Common mistakes
- After enabling the plugin, update the database schema before using username features.
- Case differences do not create distinct usernames because values are lowercased by default.
- Changing usernames remains possible unless immutableUsername is enabled.
Example: Configure the username plugin
import { betterAuth } from "better-auth";
import { username } from "better-auth/plugins";
export const auth = betterAuth({
emailAndPassword: { enabled: true },
plugins: [username()]
});Enable email/password authentication and add the username plugin to the server configuration.
When to use it
Availability validation
Prevent duplicate names before completing registration or profile changes.
Username policy enforcement
Enforce product-specific naming rules with length and custom validation settings.
Interview questions
QWhat does the username plugin provide?
The username plugin adds username support to the email/password authenticator. It lets users sign in with a username rather than an email address.
Follow-up: How would you make usernames unchangeable? Set immutableUsername to true in the plugin configuration.
QHow is the plugin installed?
Configure username() in the server plugins array and include usernameClient() in the client plugins array. The database must also be migrated or generated with the plugin's required fields and tables.
Follow-up: What must happen after adding the server plugin? Run the migration or generate the schema before using the feature.
QWhich client operations does the plugin add?
The client exposes signUp.email with a username property for registration and signIn.username for username login. It also provides updateUser for changes and isUsernameAvailable for availability checks.
Follow-up: What controls accepted names? Configure the minimum and maximum lengths and provide a validation function when the defaults are insufficient.
Related
username()usernameClient()signUp.emailsignIn.usernameupdateUserisUsernameAvailableimmutableUsername