Username

username 플러그인은 이메일 및 비밀번호 인증자에 사용자 이름 지원을 추가하는 경량 플러그인입니다. 이를 통해 사용자는 이메일 대신 사용자 이름으로 로그인하고 가입할 수 있습니다.

설치

서버에 플러그인 추가

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

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

데이터베이스 마이그레이션

마이그레이션을 실행하거나 스키마를 생성하여 필요한 필드와 테이블을 데이터베이스에 추가하세요.

npx @better-auth/cli migrate
npx @better-auth/cli generate

수동으로 필드를 추가하려면 스키마 섹션을 참조하세요.

클라이언트 플러그인 추가

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

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

사용법

가입

사용자 이름으로 사용자를 가입시키려면 클라이언트에서 제공하는 기존 signUp.email 함수를 사용할 수 있습니다. signUp 함수는 객체에 새로운 username 속성을 받아야 합니다.

POST
/sign-up/email
const { data, error } = await authClient.signUp.email({    email: "email@domain.com", // required    name: "Test User", // required    password: "password1234", // required    username: "test", // required    displayUsername: "Test User123",});
PropDescriptionType
email
사용자의 이메일.
string
name
사용자의 이름.
string
password
사용자의 비밀번호.
string
username
사용자의 사용자 이름.
string
displayUsername?
선택적 표시 사용자 이름.
string

username만 제공된 경우 displayUsername은 username의 정규화 이전 버전으로 설정됩니다. 자세한 내용은 Username Normalization 및 Display Username Normalization 섹션을 참조하세요.

로그인

사용자 이름으로 사용자를 로그인시키려면 클라이언트에서 제공하는 signIn.username 함수를 사용할 수 있습니다.

POST
/sign-in/username
const { data, error } = await authClient.signIn.username({    username: "test", // required    password: "password1234", // required});
PropDescriptionType
username
사용자의 사용자 이름.
string
password
사용자의 비밀번호.
string

사용자 이름 업데이트

사용자의 사용자 이름을 업데이트하려면 클라이언트에서 제공하는 updateUser 함수를 사용할 수 있습니다.

POST
/update-user
const { data, error } = await authClient.updateUser({    username: "new-username",});
PropDescriptionType
username?
업데이트할 사용자 이름.
string

사용자 이름 사용 가능 여부 확인

사용자 이름이 사용 가능한지 확인하려면 클라이언트에서 제공하는 isUsernameAvailable 함수를 사용할 수 있습니다.

POST
/is-username-available
const { data: response, error } = await authClient.isUsernameAvailable({    username: "new-username", // required});if(response?.available) {    console.log("사용자 이름을 사용할 수 있습니다");} else {    console.log("사용자 이름을 사용할 수 없습니다");}
PropDescriptionType
username
확인할 사용자 이름.
string

옵션

최소 사용자 이름 길이

사용자 이름의 최소 길이. 기본값은 3입니다.

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

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

최대 사용자 이름 길이

사용자 이름의 최대 길이. 기본값은 30입니다.

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

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

사용자 이름 유효성 검사기

사용자 이름의 유효성을 검사하는 함수. 사용자 이름이 유효하지 않으면 함수가 false를 반환해야 합니다. 기본적으로 사용자 이름은 영숫자, 밑줄 및 점만 포함해야 합니다.

auth.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
            }
        })
    ]
})

표시 사용자 이름 유효성 검사기

표시 사용자 이름의 유효성을 검사하는 함수. 표시 사용자 이름이 유효하지 않으면 함수가 false를 반환해야 합니다. 기본적으로 표시 사용자 이름에는 유효성 검사가 적용되지 않습니다.

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

const auth = betterAuth({
    plugins: [
        username({
            displayUsernameValidator: (displayUsername) => {
                // 영숫자, 밑줄 및 하이픈만 허용
                return /^[a-zA-Z0-9_-]+$/.test(displayUsername)
            }
        })
    ]
})

사용자 이름 정규화

사용자 이름을 정규화하는 함수 또는 정규화를 비활성화하려는 경우 false.

기본적으로 사용자 이름은 소문자로 정규화되므로 예를 들어 "TestUser"와 "testuser"는 동일한 사용자 이름으로 간주됩니다. username 필드에는 정규화된 (소문자) 사용자 이름이 포함되고 displayUsername에는 원래 username이 포함됩니다.

auth.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");
            }
        })
    ]
})

표시 사용자 이름 정규화

표시 사용자 이름을 정규화하는 함수 또는 정규화를 비활성화하려면 false.

기본적으로 표시 사용자 이름은 정규화되지 않습니다. 가입 또는 업데이트 중에 username만 제공된 경우 displayUsername은 원래 username 값 (정규화 이전)과 일치하도록 설정됩니다. displayUsername을 명시적으로 설정할 수도 있으며 그대로 유지됩니다. 사용자 지정 정규화의 경우 표시 사용자 이름을 입력으로 받아 정규화된 버전을 반환하는 함수를 제공하세요.

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

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

유효성 검사 순서

기본적으로 사용자 이름과 표시 사용자 이름은 정규화 전에 유효성이 검사됩니다. validationOrder를 post-normalization으로 설정하여 이 동작을 변경할 수 있습니다.

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

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

스키마

플러그인은 사용자 테이블에 2개의 필드를 추가해야 합니다:

Field NameTypeKeyDescription
usernamestring-사용자의 사용자 이름
displayUsernamestring-정규화되지 않은 사용자의 사용자 이름
Edit on GitHub

Previous Page

Two Factor

Next Page

Anonymous

On this page