Uploaded image for project: 'MariaDB Connector/node.js'
  1. MariaDB Connector/node.js
  2. CONJS-344

support ESM and CommonJS

    XMLWordPrintable

Details

    • Bug
    • Status: Closed (View Workflow)
    • Major
    • Resolution: Fixed
    • None
    • 3.5.3
    • other
    • 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.

      Attachments

        Activity

          People

            diego dupin Diego Dupin
            diego dupin Diego Dupin
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Git Integration

                Error rendering 'com.xiplink.jira.git.jira_git_plugin:git-issue-webpanel'. Please contact your Jira administrators.