Better Auth Harmony

Common errors

• Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'validator' from '.../node_modules/better-auth-harmony/dist/esm/index.js'

  cause `better-auth-harmony` relies on `validator.js`, which historically had inconsistent ESM support, leading to module resolution failures in certain environments.
  fix Upgrade to `better-auth-harmony@1.3.1` or newer. If using Next.js, add `better-auth-harmony` to `transpilePackages` in `next.config.js`. For Vite, add it to `ssr.noExternal` in `vite.config.js`. Alternatively, ensure Node.js 22+ is used, or pass `NODE_OPTIONS=--experimental-detect-module` for Node >= 20.10.

• TypeError: Cannot read properties of undefined (reading 'emailHarmony')

  cause Attempting to `require` or use incorrect named import syntax for `emailHarmony` or `phoneHarmony` in a CommonJS module, or when the bundler/runtime expects ESM.
  fix Ensure you are using `import { emailHarmony } from 'better-auth-harmony';` for ESM environments. Verify your `package.json` `type` field and module resolution settings if using a mixed environment.

• Login failed: Invalid credentials or unverified email.

  cause A user's email might have been normalized by `better-auth-harmony` (e.g., removing `+` aliases or changing domain casing), but the login attempt used the original unnormalized email, and `allowNormalizedSignin` option was not enabled.
  fix To allow users to sign in with either their normalized or unnormalized email, configure `emailHarmony` with `allowNormalizedSignin: true`. This will perform an additional database lookup for the normalized version of the email.

Warnings

• breaking Version 1.3.0 introduced changes to 'Match new API paths' and 'Fix compatibility with better-auth 1.5.0'. This may require updates to how `better-auth-harmony` interacts with the core `better-auth` library if you are upgrading either package across major or significant minor versions.
  Fix: Review the `better-auth` changelog for API changes in version 1.5.0 and ensure your `better-auth-harmony` configuration and usage align with the updated `better-auth` API. Consult the `better-auth-harmony` documentation for any specific migration steps related to API paths.
• gotcha Prior to version 1.3.2, a bug caused 'normalized email login failure', meaning users might have been unable to log in if their email was normalized differently than what was stored or expected.
  Fix: Upgrade to `better-auth-harmony@1.3.2` or later to resolve the normalized email login issue.
• gotcha Versions prior to 1.3.1 had compatibility issues with `validator.js` in unbundled ESM environments, potentially leading to module resolution errors.
  Fix: Upgrade to `better-auth-harmony@1.3.1` or later. If issues persist in complex ESM setups, consider workarounds mentioned in the `better-auth-harmony` documentation such as using Node.js 22+, `NODE_OPTIONS=--experimental-detect-module` for Node >= 20.10, or patching `validator.js` to include `"type": "module"` in its `package.json`.

Install

• npm install better-auth-harmony npm
• yarn add better-auth-harmony yarn
• pnpm add better-auth-harmony pnpm

Imports

• emailHarmony
  wrong:

  const { emailHarmony } = require('better-auth-harmony');

  correct:

  import { emailHarmony } from 'better-auth-harmony';

  `better-auth-harmony` is primarily designed for ESM environments. While CJS might work in some setups, named ESM imports are the recommended and most compatible approach.
• phoneHarmony
  wrong:

  import phoneHarmony from 'better-auth-harmony/phoneHarmony';

  correct:

  import { phoneHarmony } from 'better-auth-harmony';

  Both `emailHarmony` and `phoneHarmony` are named exports from the main package entry point.
• betterAuth

  import { betterAuth } from 'better-auth';

  While `betterAuth` is not from `better-auth-harmony`, it's crucial for integrating the harmony plugins. It's often imported alongside `emailHarmony` or `phoneHarmony` into your `auth` configuration file.

Quickstart

This code demonstrates how to integrate `emailHarmony` and `phoneHarmony` plugins into a `better-auth` instance. It showcases the plugin-based configuration and highlights automatic normalization and validation features.

import { betterAuth } from 'better-auth';
import { emailHarmony, phoneHarmony } from 'better-auth-harmony';
import { phoneNumber } from 'better-auth/plugins'; // Assuming this is needed for phone number handling in better-auth

// Configure your Better Auth instance with the Harmony plugins
export const auth = betterAuth({
  // ... other better-auth configuration options
  emailAndPassword: {
    enabled: true,
  },
  plugins: [
    emailHarmony({
      allowNormalizedSignin: true, // Example option: Allow users to sign in with normalized or unnormalized emails
    }),
    phoneNumber(), // better-auth's core phone number plugin
    phoneHarmony({
      matchers: { // Example matcher, customize as needed
        create: true,
        update: true,
        delete: false,
      },
    }),
  ],
  // Define a database adapter (e.g., Prisma, Drizzle)
  // database: prismaAdapter(prisma, { provider: 'postgresql' }),
});

console.log('Better Auth instance configured with Harmony plugins.');
console.log('Harmony automatically normalizes and validates emails/phone numbers.');
console.log('For example, "foo+temp@gmail.com" becomes "foo@gmail.com" and checks for disposable domains.');