Better Auth Harmony

The phoneHarmony() plugin accepts the following configuration 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. Useful for non-geographic codes like +800.
• extract (default: true): Defines the "strictness" of parsing. When true, it attempts to extract the phone number from any input string (e.g., "My phone number is (213) 373-4253").
• acceptRawInputOnError (default: false): If the normalizer fails to parse the number, the original input is used (e.g., "+12" is saved as-is).
• normalizer: Custom function to normalize phone numbers. Defaults to parsePhoneNumberWithError from libphonenumber-js/max. This can be used to infer country via the Request object (e.g., via IP geolocation).
• matchers: Customize when to run input phoneNumber validation.

The emailHarmony plugin provides email normalization and validation for better-auth. It automatically handles the creation and updating of a normalizedEmail field in your user database to allow for more flexible login and validation logic.

Key Options

• allowNormalizedSignin (boolean): If true, users can log in using any variation of their normalized email (e.g., john.doe@gmail.com can log in even if they signed up as johndoe@googlemail.com). This adds one extra database query per login attempt. Defaults to false.
• validator (function): A function to validate the email. Defaults to validateEmail (which uses validator.isEmail and mailchecker).
• normalizer (function): A function to normalize the email address. Defaults to validator.normalizeEmail.
• matchers (object): Defines which routes the plugin intercepts.
  • signIn: Routes where the plugin should look up users by normalized email if allowNormalizedSignin is enabled. Defaults to allEmailSignIn.
  • validation: Routes where the plugin should validate the email format. Defaults to allEmail.
• schema (object): Allows customizing the field name used for the normalized email in the database.

Example Usage

import emailHarmony from 'better-auth-harmony/email';
import * as matchers from 'better-auth-harmony/email/matchers';

export const auth = betterAuth({
  // ... other config options
  plugins: [
    emailHarmony({
      allowNormalizedSignin: true,
      matchers: {
        signIn: [matchers.emailOtpVerify, matchers.emailOtpForget, mathers.emailOtpReset]
      }
    })
  ]
});

import emailHarmony from 'better-auth-harmony/email';
import * as matchers from 'better-auth-harmony/email/matchers';

export const auth = betterAuth({
  // ... other config options
  plugins: [
    emailHarmony({
      allowNormalizedSignin: true,
      matchers: {
        signIn: [matchers.emailOtpVerify, matchers.emailOtpForget, matchers.emailOtpReset]
      }
    })
  ]
});

The @repo/eslint-config package provides a comprehensive ESLint flat configuration designed for TypeScript and JavaScript projects. It integrates several industry-standard plugins and rule sets to enforce best practices, security, and code style.

Key Features

• TypeScript Support: Uses typescript-eslint with strictTypeChecked and stylisticTypeChecked configurations.
• Airbnb Base: Incorporates Airbnb's best practices, errors, ES6, imports, node, strict, style, and variables rules.
• Security & Best Practices: Includes eslint-plugin-security, eslint-plugin-promise, and eslint-plugin-unicorn.
• Import Management: Uses eslint-plugin-import and eslint-plugin-simple-import-sort for organized and valid imports.
• Testing: Includes specialized configuration for vitest files (**/*.test.{js,jsx,cjs,mjs,ts,tsx,cts,mts}).
• Multi-format Support: Provides linting for .md (Markdown), .json, and .yaml/.yml files.
• Prettier Integration: Uses eslint-config-prettier to disable conflicting rules.

Environment Variables

• CHECK_REDOS: If set to 'true', the configuration extends plugin:eslint-plugin-redos/recommended to check for Regular Expression Denial of Service (ReDoS) vulnerabilities.

Because validator.js lacks proper ESM support, you may encounter errors in certain environments.

Error: Error [ERR_MODULE_NOT_FOUND]: Cannot find module

• Next.js: Add better-auth-harmony to transpilePackages in your next.config.js.
• Vite: Add better-auth-harmony to ssr.noExternal in your vite.config.ts.

Error: Cannot use import statement outside a module

Use one of the following workarounds:

• Use Node.js 22 or higher.
• For Node >= 20.10, use the --experimental-detect-module flag:
  • Via environment variable: NODE_OPTIONS=--experimental-detect-module
  • Via CLI: npx --node-options=--experimental-detect-module @better-auth/cli generate
  • Via package.json script:

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

• If these fail, use yarn patch or npm patch-package to add "type": "module" to the validator package's package.json.

The phoneHarmony plugin normalizes phone numbers in request bodies to E.164 format before they reach your auth logic. You can configure how numbers are parsed, how errors are handled, and which routes the plugin should intercept.

Configuration Options

import * as matchers from 'better-auth-harmony/phone/matchers';

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