@convex-dev/better-auth component bundling mailparser dependencies breaks Convex deployment
🪲Bug Report🔑Auth
Issue:
The @convex-dev/better-auth Convex component causes deployment failures when bundling for Convex's non-Node runtime. The component's adapterTest.ts file imports types from better-auth and better-auth/adapters/test, which pulls in the entire better-auth package including the emailOTP plugin. This plugin depends on Node.js-only mail parsing libraries (mailparser, @zone-eu/mailsplit, libmime, libbase64, libqp) that require built-in Node modules (stream, crypto, buffer, path).
Error during Convex deployment:
✘ [ERROR] Could not resolve "stream"
node_modules/mailparser/lib/mail-parser.js:6:26:
6 │ const Transform = require('stream').Transform;
╵~~~~
The package "stream" wasn't found on the file system but is built into node.
Root Cause:
When Convex bundles the @convex-dev/better-auth component during deployment, esbuild statically analyzes ALL imports in the component source, including development/test files like adapterTest.ts. These imports transitively pull in better-auth/plugins (barrel export) which includes emailOTP → mailparser → Node.js built-ins.
Our Setup:
better-auth: 1.4.9
@convex-dev/better-auth: 0.10.10
Using better-auth/minimal (not the emailOTP plugin)
Only using emailAndPassword auth method
Component registered in convex.config.ts via app.use(betterAuth)
Attempted Fixes (all failed):
Removed mcp plugin from Better Auth config (still fails)
Removed emailOTPClient from client auth config (still fails)
Created custom Node actions for password reset instead of emailOTP (still fails)
Added "use node" directives (Convex restrictions prevent this)
The Problem:
The component's development/test files (adapterTest.ts) should not be included in the production bundle, or they should use dynamic imports / conditional requires to avoid pulling in optional plugin dependencies that aren't being used.
Can you provide guidance on the recommended approach to resolve this bundling issue?
The @convex-dev/better-auth Convex component causes deployment failures when bundling for Convex's non-Node runtime. The component's adapterTest.ts file imports types from better-auth and better-auth/adapters/test, which pulls in the entire better-auth package including the emailOTP plugin. This plugin depends on Node.js-only mail parsing libraries (mailparser, @zone-eu/mailsplit, libmime, libbase64, libqp) that require built-in Node modules (stream, crypto, buffer, path).
Error during Convex deployment:
✘ [ERROR] Could not resolve "stream"
node_modules/mailparser/lib/mail-parser.js:6:26:
6 │ const Transform = require('stream').Transform;
╵
The package "stream" wasn't found on the file system but is built into node.
Root Cause:
When Convex bundles the @convex-dev/better-auth component during deployment, esbuild statically analyzes ALL imports in the component source, including development/test files like adapterTest.ts. These imports transitively pull in better-auth/plugins (barrel export) which includes emailOTP → mailparser → Node.js built-ins.
Our Setup:
better-auth: 1.4.9
@convex-dev/better-auth: 0.10.10
Using better-auth/minimal (not the emailOTP plugin)
Only using emailAndPassword auth method
Component registered in convex.config.ts via app.use(betterAuth)
Attempted Fixes (all failed):
Removed mcp plugin from Better Auth config (still fails)
Removed emailOTPClient from client auth config (still fails)
Created custom Node actions for password reset instead of emailOTP (still fails)
Added "use node" directives (Convex restrictions prevent this)
The Problem:
The component's development/test files (adapterTest.ts) should not be included in the production bundle, or they should use dynamic imports / conditional requires to avoid pulling in optional plugin dependencies that aren't being used.
Can you provide guidance on the recommended approach to resolve this bundling issue?
