Username plugin for username-based authentication
Better Auth includes a Username plugin that provides username-based authentication.
Better Auth · Plugins · all subjects
username plugin
18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Username plugin purpose and requirements
The username plugin is a lightweight plugin that adds username support to the email and password authenticator. It allows users to sign in with their username instead of their email. The plugin requires the emailAndPassword authenticator to be enabled.
Username plugin server installation
To add the username plugin to the server, import it from 'better-auth/plugins' and add it to the plugins array in betterAuth configuration. The emailAndPassword authenticator must be enabled. Example: betterAuth({ emailAndPassword: { enabled: true }, plugins: [username()] })
Username plugin client installation
To add the username plugin to the client, import usernameClient from 'better-auth/client/plugins' and add it to the plugins array in createAuthClient configuration. Example: createAuthClient({ plugins: [usernameClient()] })
Sign in with username API endpoint
The sign-in endpoint is POST /sign-in/username. Request body fields: username (string, required), password (string, required).
Update username API endpoint
The update username endpoint is POST /update-user. Request body field: username (string, optional) for updating the username. If immutableUsername is enabled, users can set username during sign-up or later if they don't already have one, but cannot change it after it has been set.
Check username availability API endpoint
The endpoint is POST /is-username-available. Request body field: username (string, required). Response contains an available boolean property indicating if the username is available.
Username plugin minUsernameLength option
The minUsernameLength option sets the minimum length of the username. Default value is 3.
Username plugin maxUsernameLength option
The maxUsernameLength option sets the maximum length of the username. Default value is 30.
Username plugin usernameValidator option
The usernameValidator option is a function that validates the username. The function should return false if the username is invalid. By default, the username should only contain alphanumeric characters, underscores, and dots.
Username plugin displayUsernameValidator option
The displayUsernameValidator option is a function that validates the display username. The function should return false if the display username is invalid. By default, no validation is applied to display username.
Username plugin usernameNormalization option
The usernameNormalization option is a function that normalizes the username, or false to disable normalization. By default, usernames are normalized to lowercase, so 'TestUser' and 'testuser' are considered the same username. The username field contains the normalized lowercase username, while displayUsername contains the original username.
Username plugin displayUsernameNormalization option
The displayUsernameNormalization option is a function that normalizes the display username, or false to disable normalization. By default, display usernames are not normalized. When only username is provided during signup or update, displayUsername will be set to the original username value before normalization. You can also explicitly set a displayUsername which will be preserved as-is.
Username plugin validationOrder option
The validationOrder option controls when validation occurs relative to normalization. It accepts an object with username and displayUsername properties, each set to either 'pre-normalization' (default) or 'post-normalization'. This determines whether validation happens before or after normalization is applied.
Username plugin disable displayUsername option
Set displayUsername to false to disable the separate displayUsername field. When disabled, the displayUsername field is not added to the user schema, displayUsername is never written during sign-up or update, inferred user/session types exclude displayUsername, and username normalization continues to work. Apply the same option to usernameClient on the client side.
Username plugin immutableUsername option
Set immutableUsername to true to prevent users from changing their username after it has been set. Users can still set a username during sign-up, or on a later profile update if they haven't already picked a username. Updating other profile fields remains allowed.
Disable username availability check endpoint
The /is-username-available endpoint can be disabled by providing disabledPaths option to the better-auth configuration: disabledPaths: ['/is-username-available']. This is useful to prevent username enumeration.
Username plugin user table schema
The plugin adds 2 fields to the user table (displayUsername is omitted when displayUsername: false): 1) username (string, unique, optional) - The username of the user; 2) displayUsername (string, optional) - Non normalized username of the user.