How to get JSDOC and Plugin to work?

[z3dev]

Not sure what's happening but I know that JSDOC is using require(). So just wondering how this plugin can actually work?

Error [ERR_REQUIRE_ESM]: require() of ES Module /Users/z3dev/dev/jscad/OpenJSCAD.org.v3.performance-part-2/node_modules/.pnpm/@alphanull+jsdoc-plugin-esnext@1.2.0/node_modules/@alphanull/jsdoc-plugin-esnext/index.js from /Users/z3dev/dev/jscad/OpenJSCAD.org.v3.performance-part-2/node_modules/.pnpm/jsdoc@4.0.4/node_modules/jsdoc/lib/jsdoc/plugins.js not supported.
Instead change the require of index.js in /Users/z3dev/dev/jscad/OpenJSCAD.org.v3.performance-part-2/node_modules/.pnpm/jsdoc@4.0.4/node_modules/jsdoc/lib/jsdoc/plugins.js to a dynamic import() which is available in all CommonJS modules.

[alphanull]

Hey z3dev, may I ask how you include the plugin?

The documented way would be including it via the jsdoc.conf.json, like this:

{
    "plugins": [
        "@alphanull/jsdoc-plugin-esnext"
    ]
}

jsdoc-plugin-esnext is in fact just a regular ES6 module, and it should at least work when you use it this way, at least with my setup (for both JSDoc 4.x and 3.x). So any more info would be appreciated.

Edit: also, please tell me your nodeJS version.

Edit2: Just checked, JSDoc loads plugins like this: plugin = await import(pluginModule);

So actually, this should be fine with both commonJS and ES6 modules.

[z3dev]

Z3s-Mac-mini:OpenJSCAD.org.v3.performance-part-2 z3dev$ node --version
v18.20.4
Z3s-Mac-mini:OpenJSCAD.org.v3.performance-part-2 z3dev$ pnpm --version
7.11.0

[z3dev]

Z3s-Mac-mini:test1 z3dev$ cat package.json 
{
  "name": "test1",
  "version": "1.0.0",
  "description": "test",
  "main": "index.js",
  "type": "module",
  "directories": {
    "test": "test"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs": "jsdoc --configure jsdoc.json"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@alphanull/jsdoc-plugin-esnext": "^1.2.0",
    "jsdoc": "^4.0.4"
  }
}

[z3dev]

I tried within a newly created NPM package. Same results.

[z3dev]

Snippet from the jsdoc configuration file.

"opts": {
   "template": "node_modules/docdash",
   "destination": "./docs",
   "tutorials": "./jsdoc/tutorials",
   "readme": "./jsdoc/assets/README.md"
 },
 "plugins": [
   "@alphanull/jsdoc-plugin-esnext",
   "plugins/markdown"
 ],
 "templates": {
   "default": {
     "staticFiles": {
       "include": [
         "./jsdoc/assets/static"
       ]
     }
   }
 },

[z3dev]

I tried a newer version of node/npm. Same results.

Z3s-Mac-mini:test1 z3dev$ node --version
v20.18.0
Z3s-Mac-mini:test1 z3dev$ npm --version
10.8.2

[z3dev]

I finally got the plugin to work. Basically, the version of NODE is choosing the installed version of JSDOC. The ES5 version of JSDOC is not installed until NODE v20.19.5. From JSDOC package.json.

 "engines": {
    "node": "^20.19.0 || ^22.12.0 || >=23.0.0"
  },

So, the requirements for this plugin should follow JSDOC.

An alternative would be creating a COMMONJS bundle of this plugin, i.e. require() support. And then older versions of NODE / JSDOC can be used. This is probably the best solution.

[alphanull]

First of all, thanks a lot for your insights. Yes I guess you are right, I should export it as commonJS, so all versions should work. Update will follow soon!

[alphanull]

OK, version 1.2.1 is now on GitHub (not on npm yet). Now uses CommonJS export. If you like try the new version with your setup, should also work with older NodeJS versions. Greatly appreciated your report and if you encounter anything else, please let me know.

[z3dev]

OK, version 1.2.1 is now on GitHub (not on npm yet). Now uses CommonJS export.

That was cool. But I wasn't expecting you to change the code to CommonJS. You can convert the ES5 based code. There are some nice bundlers that do this, like RollUp (https://rollupjs.org/)

[alphanull]

Well, I wanted to keep things simple, and since the CommonJS Version also works with newer setup I saw no need for an additional build process. So I assume I can close this ticket. Thanks for bringing up this issue! If you like, give this project a star, and/or try my JSDoc theme which works perfectly with the plugin ;)