{"id":16768,"library":"better-auth-no-disposable-emails","title":"Better-Auth Disposable Email Blocker","description":"The `better-auth-no-disposable-emails` package is a plugin for the `better-auth` authentication library, designed to prevent users from signing up or signing in with temporary or disposable email addresses. It integrates with `better-auth`'s plugin system, intercepting specified authentication endpoints (e.g., `/sign-up/email`) and validating the submitted email against a comprehensive list of known disposable email providers, powered by the `mailchecker` library. The current stable version is 0.2.0, indicating it's relatively new and in active development, though a specific release cadence isn't published. Its key differentiator is its seamless integration with `better-auth`, providing a configurable and extensible solution to enhance user quality and reduce spam registrations by blocking transient email accounts.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/koslib/better-auth-no-disposable-emails","tags":["javascript","better-auth","plugin","disposable-email","email-validation","mailchecker","typescript"],"install":[{"cmd":"npm install better-auth-no-disposable-emails","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-no-disposable-emails","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-no-disposable-emails","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a plugin for better-auth and requires it to function.","package":"better-auth","optional":false},{"reason":"Used internally for disposable email detection, but not a direct peer dependency.","package":"mailchecker","optional":false}],"imports":[{"note":"The library primarily targets ESM environments and ships with TypeScript types. While CJS is possible, ESM is the idiomatic way to import.","wrong":"const noDisposableEmails = require('better-auth-no-disposable-emails').noDisposableEmails;","symbol":"noDisposableEmails","correct":"import { noDisposableEmails } from 'better-auth-no-disposable-emails';"},{"note":"The `noDisposableEmails` function must be called to return the plugin instance, even when using default options.","wrong":"import { noDisposableEmails } from 'better-auth-no-disposable-emails';\n// ... plugins: [noDisposableEmails]","symbol":"noDisposableEmails (default options)","correct":"import { noDisposableEmails } from 'better-auth-no-disposable-emails';\n// ... plugins: [noDisposableEmails()]"},{"note":"Options are passed as an object to the function call.","symbol":"noDisposableEmails (with options)","correct":"import { noDisposableEmails } from 'better-auth-no-disposable-emails';\n// ... plugins: [noDisposableEmails({ errorMessage: '...' })]"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\";\nimport { noDisposableEmails } from \"better-auth-no-disposable-emails\";\n\n// Mock database adapter for demonstration purposes\nconst mockDatabaseAdapter = {\n  getUserByEmail: async (email: string) => {\n    if (email === 'test@example.com') return { id: '1', email: 'test@example.com' };\n    return null;\n  },\n  createUser: async (email: string, passwordHash: string) => ({\n    id: String(Date.now()),\n    email,\n  }),\n  updateUser: async (id: string, updates: any) => ({ id, ...updates }),\n  // Add other necessary methods for a better-auth database adapter\n};\n\nexport const auth = betterAuth({\n  database: mockDatabaseAdapter, // Replace with your actual database adapter\n  emailAndPassword: {\n    enabled: true,\n    // In a real app, you'd configure password hashing, JWTs, etc.\n    getHash: async (password: string) => password + '_hashed', // Placeholder\n    verifyHash: async (password: string, hash: string) => (password + '_hashed') === hash // Placeholder\n  },\n  plugins: [\n    noDisposableEmails({\n      errorMessage: \"Please use a permanent email address for registration.\",\n      customBlockedDomains: [\"temporary.io\", \"spammail.net\"],\n      paths: [\"/sign-up/email\", \"/sign-in/magic-link\"]\n    }),\n  ],\n  // ... other better-auth configuration\n});\n\nconsole.log(\"better-auth instance with disposable email plugin configured.\");\nconsole.log(\"Plugin paths: /sign-up/email, /sign-in/magic-link\");\n","lang":"typescript","description":"This quickstart demonstrates how to initialize `better-auth` and integrate the `noDisposableEmails` plugin, configuring it with a custom error message, additional blocked domains, and specific interception paths."},"warnings":[{"fix":"Ensure you call the function: `plugins: [noDisposableEmails()]`.","message":"The `noDisposableEmails` function must be invoked (e.g., `noDisposableEmails()`) when added to the `plugins` array, even if no options are passed. Forgetting the parentheses will result in the plugin not being correctly registered.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Configure the `paths` option: `noDisposableEmails({ paths: [\"/sign-up/email\", \"/sign-in/email\", \"/sign-in/magic-link\"] })`.","message":"The plugin only intercepts the paths explicitly listed in its `paths` option. By default, only `/sign-up/email` is checked. If you need to block disposable emails on sign-in, magic links, or OTP requests, you must specify those paths.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure `better-auth` is installed and updated to a compatible version: `npm install better-auth@latest`.","message":"This package is a plugin for `better-auth`. Its functionality depends entirely on the `better-auth` package being installed and correctly configured. Compatibility is guaranteed only for `better-auth` versions `>=1.5.0` as per peer dependencies.","severity":"breaking","affected_versions":"<1.5.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Call the function: `plugins: [noDisposableEmails()]` or `plugins: [noDisposableEmails({...options})]`.","cause":"The `noDisposableEmails` plugin function was added to the `plugins` array without being invoked.","error":"TypeError: noDisposableEmails is not a function or its return value is not a plugin."},{"fix":"Install or update better-auth: `npm install better-auth@latest`","cause":"The `better-auth` package is not installed or its version is older than required.","error":"Error: Peer dependency 'better-auth@>=1.5.0' not met."},{"fix":"Inform the user that temporary email addresses are not accepted. The default `errorMessage` or a custom one will be sent to the client. No code change is necessary if this behavior is desired.","cause":"A user attempted to register or sign in with an email address detected as disposable. This is the expected behavior of the plugin.","error":"400 BAD_REQUEST - DISPOSABLE_EMAIL_NOT_ALLOWED"},{"fix":"Update the plugin configuration to include the desired paths: `noDisposableEmails({ paths: [\"/sign-up/email\", \"/sign-in/email\"] })`.","cause":"The `noDisposableEmails` plugin's `paths` option does not include `/sign-in/email`.","error":"Disposable email passes through on /sign-in/email"}],"ecosystem":"npm","meta_description":null}