Username

The username plugin wraps the email and password authenticator and adds username support. This allows users to sign in and sign up with their username instead of their email.

Installation

import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"
 
const auth = await betterAuth({
    database: {
        provider: "sqlite",
        url: "./db.sqlite",
    },
    plugins: [ 
        username() 
    ] 
})

npx better-auth migrate

import { createAuthClient } from "better-auth/client"
import { usernameClient } from "better-auth/client/plugins"
 
const client = createAuthClient({
    plugins: [ 
        usernameClient() 
    ] 
})

Usage

Signup with username

To signup a user with username, you can use the signUp.username function provided by the client. The signUp function takes an object with the following properties:

• username: The username of the user.
• email: The email address of the user.
• password: The password of the user. It should be at least 8 characters long and max 32 by default.
• name: The name of the user.
• image: The image of the user. (optional)
• callbackURL: The url to redirect to after the user has signed up. (optional)

 
const data = await client.signUp.username({
    username: "test",
    email: "[email protected]",
    password: "password1234",
    name: "test",
    image: "https://example.com/image.png",
})

Signin with username

To signin a user with username, you can use the signIn.username function provided by the client. The signIn function takes an object with the following properties:

• username: The username of the user.
• password: The password of the user.
• callbackURL: The url to redirect to after the user has signed in. (optional)

 
const data = await client.signIn.username({
    username: "test",
    password: "password1234",
})

Schema

The plugin requires 1 field to be added to the user table:

Options

The username plugin doesn't require any configuration. It just needs to be added to the server and client.