github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-13 16:32:26 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[GH-ISSUE #3568] ESM/CommonJS Compatibility Issue with jose in better-auth #26972

New Issue
Closed
opened 2026-04-17 17:44:07 -05:00 by GiteaMirror · 3 comments
GiteaMirror commented 2026-04-17 17:44:07 -05:00
Owner
Copy Link

Originally created by @Tekdey on GitHub (Jul 23, 2025).
Original GitHub issue: https://github.com/better-auth/better-auth/issues/3568

Environment Information

Working Environment (macOS)

  • OS: macOS
  • Node.js version: v22.15.0
  • Docker version: 20.10.22, build 3a2c30b
  • Docker Compose version: v2.15.1
  • better-auth version: 1.2.8

Non-working Environment (Ubuntu)

  • OS: Ubuntu Linux
  • Node.js version: v22.15.0 (same as macOS, tried to match)
  • Docker version: 28.3.2, build 578ccf6
  • Docker Compose version: 1.29.2
  • better-auth version: 1.2.8 (tried 1.2.10 and 1.3.3 previously)

Description of Issue

When running a TypeScript API project with better-auth in a Docker container on Ubuntu Linux, the application crashes with an ESM/CommonJS compatibility error. The same codebase works properly on macOS with identical Node.js version.

Error Message

Error [ERR_REQUIRE_ESM]: require() of ES Module /app/node_modules/jose/dist/webapi/index.js from /app/node_modules/better-auth/dist/shared/better-auth.DMLYdcsC.cjs not supported.
Instead change the require of index.js in /app/node_modules/better-auth/dist/shared/better-auth.DMLYdcsC.cjs to a dynamic import() which is available in all CommonJS modules.

Stack Trace

at require.extensions..jsx.require.extensions..js (/tmp/ts-node-dev-hook-40843042720491574.js:114:20)
at Object.nodeDevHook [as .js] (/app/node_modules/ts-node-dev/lib/hook.js:63:13)
at Object.<anonymous> (/app/node_modules/better-auth/dist/shared/better-auth.DMLYdcsC.cjs:10:1)
at Module._compile (/app/node_modules/source-map-support/source-map-support.js:521:25)
at require.extensions..jsx.require.extensions..js (/tmp/ts-node-dev-hook-40843042720491574.js:114:20)
at Object.nodeDevHook [as .js] (/app/node_modules/ts-node-dev/lib/hook.js:63:13)
at Object.<anonymous> (/app/node_modules/better-auth/dist/shared/better-auth.BzwQYq5t.cjs:7:15)
at Module._compile (/app/node_modules/source-map-support/source-map-support.js:521:25)
at require.extensions..jsx.require.extensions..js (/tmp/ts-node-dev-hook-40843042720491574.js:114:20)
at Object.nodeDevHook [as .js] (/app/node_modules/ts-node-dev/lib/hook.js:63:13)
at Object.<anonymous> (/app/node_modules/better-auth/dist/api/index.cjs:4:17)

Attempted Solutions

  1. Downgraded better-auth from 1.3.3 to 1.2.10 and then to 1.2.8 (version that works on macOS)
  2. Modified imports in our codebase from ES modules syntax to CommonJS (using require instead of import)
  3. Used the exact same Node.js version (v22.15.0) on both environments
  4. Cleaned Docker containers, volumes, and node_modules between attempts

Additional Information

  • The error specifically relates to better-auth trying to use require('jose') in its CommonJS files, but jose is an ESM-only package

  • This works on macOS but fails on Ubuntu Linux with identical Node.js versions and package versions

  • Looking at GitHub issues #829 and #3260, this appears to be a known issue but existing solutions don't work in our environment

Proposed Change

The error message suggests changing the require('jose') call to a dynamic import(), which should be compatible with both module systems. This would need to be applied to all affected files in the better-auth codebase.

Question

Is there any recommendation for making this work consistently across platforms without having to manually patch node_modules files? Or could the better-auth package be updated to handle ESM/CommonJS interoperability properly?

Thank you for your help!

Originally created by @Tekdey on GitHub (Jul 23, 2025). Original GitHub issue: https://github.com/better-auth/better-auth/issues/3568 ## Environment Information ### Working Environment (macOS) - **OS**: macOS - **Node.js version**: v22.15.0 - **Docker version**: 20.10.22, build 3a2c30b - **Docker Compose version**: v2.15.1 - **better-auth version**: 1.2.8 ### Non-working Environment (Ubuntu) - **OS**: Ubuntu Linux - **Node.js version**: v22.15.0 (same as macOS, tried to match) - **Docker version**: 28.3.2, build 578ccf6 - **Docker Compose version**: 1.29.2 - **better-auth version**: 1.2.8 (tried 1.2.10 and 1.3.3 previously) ## Description of Issue When running a TypeScript API project with better-auth in a Docker container on Ubuntu Linux, the application crashes with an ESM/CommonJS compatibility error. The same codebase works properly on macOS with identical Node.js version. ### Error Message ``` Error [ERR_REQUIRE_ESM]: require() of ES Module /app/node_modules/jose/dist/webapi/index.js from /app/node_modules/better-auth/dist/shared/better-auth.DMLYdcsC.cjs not supported. Instead change the require of index.js in /app/node_modules/better-auth/dist/shared/better-auth.DMLYdcsC.cjs to a dynamic import() which is available in all CommonJS modules. ``` ### Stack Trace ``` at require.extensions..jsx.require.extensions..js (/tmp/ts-node-dev-hook-40843042720491574.js:114:20) at Object.nodeDevHook [as .js] (/app/node_modules/ts-node-dev/lib/hook.js:63:13) at Object.<anonymous> (/app/node_modules/better-auth/dist/shared/better-auth.DMLYdcsC.cjs:10:1) at Module._compile (/app/node_modules/source-map-support/source-map-support.js:521:25) at require.extensions..jsx.require.extensions..js (/tmp/ts-node-dev-hook-40843042720491574.js:114:20) at Object.nodeDevHook [as .js] (/app/node_modules/ts-node-dev/lib/hook.js:63:13) at Object.<anonymous> (/app/node_modules/better-auth/dist/shared/better-auth.BzwQYq5t.cjs:7:15) at Module._compile (/app/node_modules/source-map-support/source-map-support.js:521:25) at require.extensions..jsx.require.extensions..js (/tmp/ts-node-dev-hook-40843042720491574.js:114:20) at Object.nodeDevHook [as .js] (/app/node_modules/ts-node-dev/lib/hook.js:63:13) at Object.<anonymous> (/app/node_modules/better-auth/dist/api/index.cjs:4:17) ``` ## Attempted Solutions 1. Downgraded better-auth from 1.3.3 to 1.2.10 and then to 1.2.8 (version that works on macOS) 2. Modified imports in our codebase from ES modules syntax to CommonJS (using require instead of import) 3. Used the exact same Node.js version (v22.15.0) on both environments 4. Cleaned Docker containers, volumes, and node_modules between attempts ## Additional Information - The error specifically relates to better-auth trying to use `require('jose')` in its CommonJS files, but jose is an ESM-only package - This works on macOS but fails on Ubuntu Linux with identical Node.js versions and package versions - Looking at GitHub issues #829 and #3260, this appears to be a known issue but existing solutions don't work in our environment ## Proposed Change The error message suggests changing the `require('jose')` call to a dynamic `import()`, which should be compatible with both module systems. This would need to be applied to all affected files in the better-auth codebase. ## Question Is there any recommendation for making this work consistently across platforms without having to manually patch node_modules files? Or could the better-auth package be updated to handle ESM/CommonJS interoperability properly? Thank you for your help!
GiteaMirror added the locked label 2026-04-17 17:44:07 -05:00
GiteaMirror commented 2026-04-17 17:44:09 -05:00
Author
Owner
Copy Link

@dosubot[bot] commented on GitHub (Jul 23, 2025):

Hi @Tekdey! I'm Dosu and I’m helping the better-auth team.

The root cause is that better-auth imports the ESM-only jose package using static imports in both its ESM and CommonJS builds. This triggers ERR_REQUIRE_ESM when require('better-auth') is used in a CommonJS project, because jose cannot be loaded with require() in this context. There is currently no dynamic import workaround or compatibility layer in better-auth, and no official roadmap for CommonJS support. Pinning to better-auth@1.2.10 is the only reliable workaround for CommonJS projects right now; otherwise, you’ll need to migrate your project to ESM or experiment with custom dynamic import hacks, which are not officially supported or documented by better-auth (source).

If you want to use require('jose') in CommonJS, Node.js v22.12.0 or later (in the v22.x series) is required. Older v22.x releases (including v22.15.0) do not support this, which may explain why you see different behavior between environments even with the same nominal Node.js version (source).

There is no cross-platform fix without patching node_modules or migrating to ESM. Updating better-auth to use dynamic import() for jose would be required for universal compatibility, but this is not implemented yet.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other  Chat with Dosu Join Discord Share on X

<!-- gh-comment-id:3109511048 --> @dosubot[bot] commented on GitHub (Jul 23, 2025): <!-- Greeting --> Hi @Tekdey! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the better-auth team. <!-- Answer --> The root cause is that better-auth imports the ESM-only jose package using static imports in both its ESM and CommonJS builds. This triggers ERR_REQUIRE_ESM when require('better-auth') is used in a CommonJS project, because jose cannot be loaded with require() in this context. There is currently no dynamic import workaround or compatibility layer in better-auth, and no official roadmap for CommonJS support. Pinning to better-auth@1.2.10 is the only reliable workaround for CommonJS projects right now; otherwise, you’ll need to migrate your project to ESM or experiment with custom dynamic import hacks, which are not officially supported or documented by better-auth [(source)](https://github.com/better-auth/better-auth/issues/3260). If you want to use require('jose') in CommonJS, Node.js v22.12.0 or later (in the v22.x series) is required. Older v22.x releases (including v22.15.0) do not support this, which may explain why you see different behavior between environments even with the same nominal Node.js version [(source)](https://github.com/better-auth/better-auth/issues/3260). There is no cross-platform fix without patching node_modules or migrating to ESM. Updating better-auth to use dynamic import() for jose would be required for universal compatibility, but this is not implemented yet. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/e3981fde-a0df-4be8-9cf6-a1cf20e8b627?feedback_type=other)</sup>&nbsp;&nbsp;[![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/3568)
GiteaMirror commented 2026-04-17 17:44:11 -05:00
Author
Owner
Copy Link

@aymericzip commented on GitHub (Jul 26, 2025):

I got a similar error error in a CJS env with nanostore

Error [ERR_REQUIRE_CYCLE_MODULE]: Cannot require() ES Module /.pnpm/nanostores@0.10.3/node_modules/nanostores/index.js in a cycle

I fixed it by replacing nanostores by nanostores-cjs in my pnpm monorepo

package.json:

  "pnpm": {
    "overrides": {
      "nanostores": "npm:nanostores-cjs@0.7.1",
    }
  },
<!-- gh-comment-id:3123379124 --> @aymericzip commented on GitHub (Jul 26, 2025): I got a similar error error in a CJS env with nanostore ```bash Error [ERR_REQUIRE_CYCLE_MODULE]: Cannot require() ES Module /.pnpm/nanostores@0.10.3/node_modules/nanostores/index.js in a cycle ``` I fixed it by replacing `nanostores` by `nanostores-cjs` in my pnpm monorepo package.json: ```json "pnpm": { "overrides": { "nanostores": "npm:nanostores-cjs@0.7.1", } }, ```
GiteaMirror commented 2026-04-17 17:44:13 -05:00
Author
Owner
Copy Link

@Kinfe123 commented on GitHub (Jul 30, 2025):

can you please send me your ts config please because the latest node version support esm-only package by adding require(esm). but still if you are in dual or cjs support you might have a resolving issue.That said, we’re planning to drop CommonJS support going forward. Maintaining dual builds introduces a lot of overhead, both in terms of complexity and performance and it significantly increases package size by duplicating the module output. Since most of our codebase still supports dual mode for now, we want to make the transition smooth. But long term, ESM-only will be the direction we maintain.

<!-- gh-comment-id:3135896785 --> @Kinfe123 commented on GitHub (Jul 30, 2025): can you please send me your ts config please because the latest node version support esm-only package by adding require(esm). but still if you are in dual or cjs support you might have a resolving issue.That said, we’re planning to drop CommonJS support going forward. Maintaining dual builds introduces a lot of overhead, both in terms of complexity and performance and it significantly increases package size by duplicating the module output. Since most of our codebase still supports dual mode for now, we want to make the transition smooth. But long term, ESM-only will be the direction we maintain.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label locked
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#26972
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?