better-auth-harmony

Better Auth Harmony

A better-auth plugin for email & phone normalization and additional validation, blocking over 55,000 temporary email domains.

Email normalization: [e-mail] -> [e-mail]
Phone normalization: [phone] -> [phone]
Validation: [e-mail] -> Blocked

• Email
  • Getting Started
  • Options
  • Schema
  • Troubleshooting ESM
• Phone number
  • Getting Started
  • Options

Email

Getting Started

1. Install the plugin

npm i better-auth-harmony

2. Add the plugin to your auth config

// auth.ts
import { betterAuth } from 'better-auth';
import { emailHarmony } from 'better-auth-harmony';

export const auth = betterAuth({
  // ... other config options
  plugins: [emailHarmony()]
});

3. Migrate the database

npx @better-auth/cli migrate

or

npx @better-auth/cli generate

See the Schema section to add the fields manually.

Troubleshooting ESM

The validator.js package lacks proper ESM support. Please open an issue in this repo if the following workarounds don't help.

Error Error [ERR_MODULE_NOT_FOUND]: Cannot find module

Next.js

Add better-auth-harmony to transpilePackages in next.config

Vite

Add better-auth-harmony to ssr.noExternal in vite.config

Error Cannot use import statement outside a module

Workarounds

• Use NodeJs 22 or higher
• Or use NODE_OPTIONS=--experimental-detect-module for Node >= 20.10

Either as an environment variable, or via:

npx --node-options=--experimental-detect-module @better-auth/cli generate

or as a local script in package.json:

{
  "scripts": {
    "auth-generate": "NODE_OPTIONS=--experimental-detect-module cli generate"
  }
}

If none of the above works, consider yarn patch or npm patch-package to add "type": "module" to validator's package.json.

Options

• allowNormalizedSignin (default=false) - Allow logging in with any version of the unnormalized email address. For example, a user who signed up with the email [e-mail] may also log in with [e-mail]. Makes 1 extra database query for every login attempt.
• validator - Custom function to validate email. By default uses validator.js and Mailchecker.
• normalizer - Custom function to normalize the email address. By default uses validator.js/normalizeEmail().
• matchers - Customize when to run input email validation and normalization. Normalization always runs on user creation and update regardless of this setting.

Schema

The emailHarmony plugin requires an additional field in the user table:

Field Name	Type	Optional	Unique	Description
normalizedEmail	string	True	True	User's email address after normalization

The normalizedEmail field being unique prevents users from signing up with throwaway variations of the same email address.

Phone number

[!NOTE] Unlike emailHarmony, phone number normalization intercepts and modifies the user's phoneNumber, permitting only normalized numbers in the backend.

Getting Started

1. Install the plugin

npm i better-auth-harmony

2. Add the plugin to your auth config

// auth.ts
import { betterAuth } from 'better-auth';
import { phoneNumber } from 'better-auth/plugins';
import { phoneHarmony } from 'better-auth-harmony';

export const auth = betterAuth({
  // ... other config options
  plugins: [phoneNumber(), phoneHarmony()]
});

See the better-auth phoneNumber plugin documentation for information on configuring the phoneNumber(), including validation.

Options

• defaultCountry - Default country for numbers written in non-international form (without a + sign).
• defaultCallingCode - Default calling code for numbers written in non-international form (without a + sign). Useful for parsing non-geographic codes such as +800 numbers.
• extract (default=true) - Defines the "strictness" of parsing a phone number. By default, it will attempt to extract the phone number from any input string, such as "My phone number is [phone]".
• acceptRawInputOnError (default=false) - If the normalizer throws, for example because it is unable to parse the phone number, use the original input. For example, the phone number "+12" will be saved as-is to the database.
• normalizer - Custom function to normalize phone number. Default uses parsePhoneNumberWithError from libphonenumber-js/max. Can be used to infer the country through the Request object, for example using IP address geolocation.
• matchers - Customize when to run input phoneNumber validation.