mirror of
https://github.com/better-auth/better-auth.git
synced 2026-06-01 03:46:39 -05:00
128 lines
3.5 KiB
Plaintext
128 lines
3.5 KiB
Plaintext
---
|
|
title: Username
|
|
description: Username plugin
|
|
---
|
|
|
|
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
|
|
|
|
<Steps>
|
|
<Step>
|
|
### Add Plugin to the server
|
|
|
|
```ts title="auth.ts"
|
|
import { betterAuth } from "better-auth"
|
|
import { username } from "better-auth/plugins"
|
|
|
|
const auth = await betterAuth({
|
|
plugins: [ // [!code highlight]
|
|
username() // [!code highlight]
|
|
] // [!code highlight]
|
|
})
|
|
```
|
|
</Step>
|
|
<Step>
|
|
### Migrate the database
|
|
|
|
Run the migration to add the required fields to the user table.
|
|
|
|
This will add the following fields to the **user** table:
|
|
|
|
- `username`: The username of the user.
|
|
|
|
```bash
|
|
npx better-auth migrate
|
|
```
|
|
</Step>
|
|
<Step>
|
|
### Add the client plugin
|
|
|
|
```ts title="client.ts"
|
|
import { createAuthClient } from "better-auth/client"
|
|
import { usernameClient } from "better-auth/client/plugins"
|
|
|
|
const client = createAuthClient({
|
|
plugins: [ // [!code highlight]
|
|
usernameClient() // [!code highlight]
|
|
] // [!code highlight]
|
|
})
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## 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)
|
|
|
|
```ts title="client.ts"
|
|
import { createAuthClient } from "better-auth/client"
|
|
import { usernameClient } from "better-auth/client/plugins"
|
|
const client = createAuthClient({
|
|
plugins: [ // [!code highlight]
|
|
usernameClient() // [!code highlight]
|
|
] // [!code highlight]
|
|
})
|
|
// ---cut---
|
|
|
|
const data = await client.signUp.username({
|
|
username: "test",
|
|
email: "test@email.com",
|
|
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)
|
|
|
|
```ts title="client.ts"
|
|
import { createAuthClient } from "better-auth/client"
|
|
import { usernameClient } from "better-auth/client/plugins"
|
|
const client = createAuthClient({
|
|
plugins: [ // [!code highlight]
|
|
usernameClient() // [!code highlight]
|
|
] // [!code highlight]
|
|
})
|
|
// ---cut---
|
|
|
|
const data = await client.signIn.username({
|
|
username: "test",
|
|
password: "password1234",
|
|
})
|
|
```
|
|
|
|
## Schema
|
|
|
|
The plugin requires 1 field to be added to the user table:
|
|
|
|
<DatabaseTable
|
|
fields={[
|
|
{
|
|
name: "username",
|
|
type: "string",
|
|
description: "The username of the user",
|
|
isUnique: true
|
|
},
|
|
]}
|
|
/>
|
|
|
|
## Options
|
|
|
|
The username plugin doesn't require any configuration. It just needs to be added to the server and client.
|