v10.0.0: `"type": "module"` + UMD `main` breaks default import under Vite/Vitest (`import auth0 from 'auth0-js'` yields `undefined`)

[MatthewHarrigan]

Summary

v10.0.0 added "type": "module" to package.json but kept main pointing at the UMD bundle (dist/auth0.min.js) and did not add an exports map. Bundlers that respect "type": "module" (Vite, Vitest, modern esbuild) load the UMD file as ESM and find no top-level export statements — so the default import resolves to undefined, breaking the documented new auth0.WebAuth(...) / new auth0.Authentication(...) usage shown in the README.

Reproduction

mkdir auth0-v10-repro && cd auth0-v10-repro
npm init -y
npm i auth0-js@10.0.0 vite vitest
cat > probe.test.js <<'EOF'
import auth0 from 'auth0-js';
import * as ns from 'auth0-js';

test('default + namespace shape', () => {
  console.log('default import:', auth0);                 // undefined
  console.log('namespace keys :', Object.keys(ns));      // []
});
EOF
npx vitest run probe.test.js

Output:

default import: undefined
namespace keys: []

Importing the ESM bundle directly works as expected:

import auth0 from 'auth0-js/dist/auth0.min.esm.js';
// → { Authentication: [Function], Management: [Function], WebAuth: [Function], version: '10.0.0' }

Jest is unaffected because its resolver loads main as CJS and the UMD wrapper's exports.X = ... writes work correctly under CJS execution.

Why this happens

package.json in v10:

{
  "type": "module",
  "main": "dist/auth0.min.js",
  "module": "dist/auth0.min.esm.js"
}

• Node ESM / Vite / Vitest / modern esbuild: sees "type": "module", loads the resolved file (main in many configs) as ESM. The UMD's IIFE writes to module.exports / exports.X at runtime, which produces no ESM exports → empty namespace, undefined default.
• Jest: falls back to CJS resolution, runs main as CJS, UMD writes succeed.

The module field is supposed to win for ESM-aware bundlers, but in practice Vite's resolution interacts with "type": "module" such that the UMD main gets pulled in as ESM. The exports field is the modern, authoritative way to disambiguate.

Impact

Every consumer using Vite, Vitest, or recent esbuild (i.e., the default tooling for new React/Vue/Svelte/Solid apps since ~2023) breaks on v9 → v10 upgrade. The failure surfaces as a runtime TypeError: Cannot read properties of undefined (reading 'Authentication') (or 'WebAuth') at whatever call site first uses the SDK constructors — typically inside componentDidMount / route initialization.

The README itself documents the broken usage:

import auth0 from 'auth0-js';
var webAuth = new auth0.WebAuth({ ... });

Suggested fix

Add a conditional exports map so each environment receives the right bundle:

{
  "type": "module",
  "main": "dist/auth0.min.js",
  "module": "dist/auth0.min.esm.js",
  "exports": {
    ".": {
      "import": "./dist/auth0.min.esm.js",
      "require": "./dist/auth0.min.js",
      "default": "./dist/auth0.min.esm.js"
    }
  }
}

Alternatives:

• Point main at the ESM bundle (simpler, but breaks any consumer that's required CJS via require('auth0-js')).
• Drop "type": "module" (regresses the v10 intent of marking the package as ESM).

Either of these restores the documented import auth0 from 'auth0-js' usage across all bundlers.

Workarounds for affected consumers

1. Pin to ^9.29.0 until v10 packaging is fixed.
2. Vite/Vitest only: alias auth0-js to its ESM bundle in your bundler config:

   resolve: { alias: { 'auth0-js': 'auth0-js/dist/auth0.min.esm.js' } }

Environment

• auth0-js@10.0.0
• Vite 7.x, Vitest 4.x
• Node 22.x and 24.x (same behavior)
• Bundler config: defaults from @vitejs/plugin-react

Happy to send a PR with the exports map if maintainers prefer that path.

[amitsingh05667]

@MatthewHarrigan Thanks for the detailed report and reproduction.

Please feel free to open a PR for the suggested exports map fix - happy to review it.

[MatthewHarrigan]

Thanks @amitsingh05667! I have raised a PR to add the exports map. Would you be able to review 🙏