{"id":16603,"library":"better-auth-harmony","title":"Better Auth Harmony","description":"Better Auth Harmony is a plugin for the `better-auth` framework, designed to enhance user input handling by providing robust validation and normalization functionalities. It specifically targets email addresses, detecting and blocking disposable domains, as well as standardizing phone numbers. The library aims to improve data quality and security within applications leveraging `better-auth` for user authentication. The current stable version is `1.3.2`, with a release cadence that includes regular patch and minor updates to address bugs and introduce new features. Its primary differentiator lies in its deep integration with the `better-auth` ecosystem, offering specialized validation and normalization that aligns with `better-auth`'s architecture, thereby providing a comprehensive solution for managing user identity data.","status":"active","version":"1.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/GeKorm/better-auth-harmony","tags":["javascript","authentication","better-auth","email","domains","disposable","phone number","mobile","typescript"],"install":[{"cmd":"npm install better-auth-harmony","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-harmony","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-harmony","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for `better-auth` and requires it as a peer dependency for core authentication functionalities.","package":"better-auth","optional":false}],"imports":[{"note":"`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.","wrong":"const { emailHarmony } = require('better-auth-harmony');","symbol":"emailHarmony","correct":"import { emailHarmony } from 'better-auth-harmony';"},{"note":"Both `emailHarmony` and `phoneHarmony` are named exports from the main package entry point.","wrong":"import phoneHarmony from 'better-auth-harmony/phoneHarmony';","symbol":"phoneHarmony","correct":"import { phoneHarmony } from 'better-auth-harmony';"},{"note":"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.","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth';"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { emailHarmony, phoneHarmony } from 'better-auth-harmony';\nimport { phoneNumber } from 'better-auth/plugins'; // Assuming this is needed for phone number handling in better-auth\n\n// Configure your Better Auth instance with the Harmony plugins\nexport const auth = betterAuth({\n  // ... other better-auth configuration options\n  emailAndPassword: {\n    enabled: true,\n  },\n  plugins: [\n    emailHarmony({\n      allowNormalizedSignin: true, // Example option: Allow users to sign in with normalized or unnormalized emails\n    }),\n    phoneNumber(), // better-auth's core phone number plugin\n    phoneHarmony({\n      matchers: { // Example matcher, customize as needed\n        create: true,\n        update: true,\n        delete: false,\n      },\n    }),\n  ],\n  // Define a database adapter (e.g., Prisma, Drizzle)\n  // database: prismaAdapter(prisma, { provider: 'postgresql' }),\n});\n\nconsole.log('Better Auth instance configured with Harmony plugins.');\nconsole.log('Harmony automatically normalizes and validates emails/phone numbers.');\nconsole.log('For example, \"foo+temp@gmail.com\" becomes \"foo@gmail.com\" and checks for disposable domains.');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Upgrade to `better-auth-harmony@1.3.2` or later to resolve the normalized email login issue.","message":"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.","severity":"gotcha","affected_versions":"<1.3.2"},{"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`.","message":"Versions prior to 1.3.1 had compatibility issues with `validator.js` in unbundled ESM environments, potentially leading to module resolution errors.","severity":"gotcha","affected_versions":"<1.3.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"`better-auth-harmony` relies on `validator.js`, which historically had inconsistent ESM support, leading to module resolution failures in certain environments.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'validator' from '.../node_modules/better-auth-harmony/dist/esm/index.js'"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'emailHarmony')"},{"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.","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.","error":"Login failed: Invalid credentials or unverified email."}],"ecosystem":"npm"}