Details
-
Bug
-
Status: Closed (View Workflow)
-
Major
-
Resolution: Fixed
-
None
-
None
Description
3.5.x was published as a pure ESM package ("type": "module").
this breaks:
- CJS consumers. require('mariadb') fails on Node < 22.12 with ERR_REQUIRE_ESM. Even on Node 22.12+ it emits an ExperimentalWarning.
- Default import. import mariadb from 'mariadb' worked on 3.4.x because the CJS module synthesized a default export. ESM modules don't synthesize one, so the same code now throws "does not provide an export named 'default'".
- TypeScript under moduleResolution: "Node16" / "NodeNext" / "Bundler". The .d.ts files used bare relative imports (./share), then (in 3.5.2) .d.ts extensions — both rejected by strict resolution modes (TS2834 / TS2846).
Fix
Dual-package layout:
- ESM source unchanged: promise.js, callback.js, lib/*.js.
- CJS consumers get a minified bundle at dist/promise.cjs + dist/callback.cjs, built with esbuild via prepublishOnly. Works on Node 18+ with no flags or warnings.
- TypeScript: paired type files — .d.ts for the import condition, .d.cts for require — both using .js / .cjs extensions in their relative imports (the convention TS requires under Node16/NodeNext).
- Default export restored on both entry points, so import mariadb from 'mariadb' works again.
Looking ahead to 4.0
The bundled dist/ is a transitional workaround. The plan for the next major version (4.0) is to drop it and ship as pure ESM. That only becomes viable when every supported Node version can transparently require() ESM (without --experimental-require-module which Node 20 still needs) and without an ExperimentalWarning (which Node 22 emits until 23+).
In practice that means waiting until the minimum supported version is Node 24 LTS.