Better Auth

https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/
Admin
Better Auth is an authentication framework that provides plugins like username support to add...
Tokens:2,220
Snippets:15
Trust Score:7.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Check Username Availability

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Defines the TypeScript type for the `isUsernameAvailable` function and provides an example of how to check username availability and log the result.

```ts
type isUsernameAvailable = {
    /**
     * The username to check.
    */
    username: string = "new-username"
}

if(response?.available) {
    console.log("Username is available");
} else {
    console.log("Username is not available");
}
```

--------------------------------

### Configure Minimum Username Length

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Sets the minimum allowed length for usernames during configuration. This example demonstrates setting the `minUsernameLength` option to 5.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            minUsernameLength: 5
        })
    ]
})
```

--------------------------------

### Add Username Plugin to Server

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Integrates the username plugin into the Better Auth server configuration. This involves importing the plugin and adding it to the list of plugins in the `betterAuth` setup.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

export const auth = betterAuth({
    plugins: [
        username()
    ]
})
```

--------------------------------

### Configure Maximum Username Length

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Sets the maximum allowed length for usernames during configuration. This example demonstrates setting the `maxUsernameLength` option to 100.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            maxUsernameLength: 100
        })
    ]
})
```

--------------------------------

### Migrate Database for Username Support

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Applies database migrations to add the necessary fields and tables for username support. This command is executed via the Better Auth CLI.

```bash
npx @better-auth/cli migrate
```

--------------------------------

### Generate Database Schema for Username Support

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Generates the database schema to include fields and tables required for username authentication. This command is executed via the Better Auth CLI.

```bash
npx @better-auth/cli generate
```

--------------------------------

### Sign Up with Username

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Defines the TypeScript type for the `signUpEmail` function, which now includes an optional `username` and `displayUsername` field for user registration.

```ts
type signUpEmail = {
    /**
     * The email of the user.
    */
    email: string = "email@domain.com"
    /**
     * The name of the user.
    */
    name: string = "Test User"
    /**
     * The password of the user.
    */
    password: string = "password1234"
    /**
     * The username of the user.
    */
    username: string = "test"
    /**
     * An optional display username of the user.
    */
    displayUsername?: string = "Test User123"
}
```

--------------------------------

### Add Username Plugin to Client

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Integrates the username client plugin for Better Auth. This allows client-side applications to interact with username-based authentication features.

```ts
import { createAuthClient } from "better-auth/client"
import { usernameClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [
        usernameClient()
    ]
})
```

--------------------------------

### Sign In with Username

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Defines the TypeScript type for the `signInUsername` function, used for authenticating users via their username and password.

```ts
type signInUsername = {
    /**
     * The username of the user.
    */
    username: string = "test"
    /**
     * The password of the user.
    */
    password: string = "password1234"
}
```

--------------------------------

### Configure Username Validation Order

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Specifies the order of validation relative to normalization. By default, validation occurs before normalization. Setting 'validationOrder' to 'post-normalization' changes this behavior for both username and display username.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            validationOrder: {
                username: "post-normalization",
                displayUsername: "post-normalization",
            }
        })
    ]
})
```

--------------------------------

### Configure Username Normalization

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Defines a function to normalize usernames. If set to false, normalization is disabled. By default, usernames are converted to lowercase, ensuring 'TestUser' and 'testuser' are treated as the same. The 'username' field stores the normalized version, while 'displayUsername' retains the original.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            usernameNormalization: (username) => {
                return username.toLowerCase()
                    .replaceAll("0", "o")
                    .replaceAll("3", "e")
                    .replaceAll("4", "a");
            }
        })
    ]
})
```

--------------------------------

### Configure Display Username Normalization

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Sets a function to normalize display usernames, or false to disable it. By default, display usernames are not normalized. If only 'username' is provided, 'displayUsername' defaults to the original 'username' before normalization. Custom normalization can be applied by providing a function.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            displayUsernameNormalization: (displayUsername) => displayUsername.toLowerCase(),
        })
    ]
})
```

--------------------------------

### Update User with New Username

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Defines the TypeScript type for the `updateUser` function, allowing users to change their username. The `username` field is optional.

```ts
type updateUser = {
    /**
     * The username to update.
    */
    username?: string = "new-username"
}
```

--------------------------------

### Configure Username Validation

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Sets a custom validator function for the username. This function determines if a username is valid, returning false for invalid usernames. The default validation allows alphanumeric characters, underscores, and dots.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            usernameValidator: (username) => {
                if (username === "admin") {
                    return false
                }
                return true
            }
        })
    ]
})
```

--------------------------------

### Configure Display Username Validation

Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/username

Sets a custom validator for the display username. This function returns false if the display username is invalid. By default, no validation is applied to the display username.

```ts
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username({
            displayUsernameValidator: (displayUsername) => {
                // Allow only alphanumeric characters, underscores, and hyphens
                return /^[a-zA-Z0-9_-]+$/.test(displayUsername)
            }
        })
    ]
})
```
Tokens:
Raw