Skip to content

Node.js: add ESM support (dual CJS + ESM build) #577

Description

@kalwalt

Summary

Add ESM consumption for the experimental Node.js build so named imports work:

import { ARControllerNFT, ARToolkitNFT } from '@webarkit/jsartoolkit-nft';

Today the Node build is commonjs2 only, so consumers must use require() or a default import (Node can't statically read named exports from the CJS bundle). This is the top capability gap for the Node support.

Proposed approach — dual CJS + ESM (non-breaking)

  • Keep the existing dist/ARToolkitNFT_node.js (CommonJS).
  • Add a separate ESM bundle, e.g. dist/ARToolkitNFT_node.mjs, via a webpack target with output.library.type: "module" + experiments.outputModule: true (and target: "node").
  • Wire package.json exports so the Node entry serves both:
    "node": {
      "import": { "types": "./types/src/index_node.d.ts", "default": "./dist/ARToolkitNFT_node.mjs" },
      "require": { "types": "./types/src/index_node.d.ts", "default": "./dist/ARToolkitNFT_node.js" }
    }
  • main and the existing require() path stay unchanged → no breaking change.

Alternatives considered

  • ESM-only node build — cleaner single artifact, but breaks existing require() consumers. Rejected.

Tasks

  • Add ESM webpack target for the node entry (output.library.type: "module").
  • Update tools/makem.js if a different wasm flavor is needed for ESM (verify the existing _node_wasm glue works under ESM).
  • Add import/require conditions to the exports map.
  • Add/verify an ESM example (example.mjs) using import { ARControllerNFT }.
  • Update README Node.js section (the "named import not yet supported" caveat).

Notes

  • Experimental Node.js support — see Feature node libs #140. Work targets the dev branch.
  • Verify with npm run build-ts + a runnable ESM example before release.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions