What distribution(s) to target (CJS, ESM, ...)?

[chrisjsewell]

Certainly compared to Python (one distribution works for all v3.x), JS/TS is a bit of a mess when it comes to packaging libraries: not only do you need to think about the version/format of javascript (and compatibility with third-party modules), but also node vs browser compatibility.

Essentially CommonJS modules are a legacy format, that many third party packages still use, whereas ES modules are now the ~official standard and "future" of javascript (and are now basically supported in all browsers: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules, see also https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/).
Again comparing to Python, it feels like JS/TS is in a similar situation to when python packages were transitioning from v2 to v3 (and so support was necessary for both).

Using rollup you can actually target multiple build formats:

• https://rollupjs.org/guide/en/#outputformat (default esm)
• https://rollupjs.org/guide/en/#why-are-es-modules-better-than-commonjs-modules

Currently, I have it set to do a "hybrid" build with: https://github.com/executablebooks/markdown-it-plugin-template/blob/master/rollup.config.js, and in package.json pointing to either with:

markdown-it-plugin-template/package.json

Lines 13 to 24 in d6cd3ea

	"main": "dist/cjs/index.js",
	"module": "dist/mjs/index.js",
	"types": "dist/index.d.ts",
	"files": [
	"dist"
	],
	"exports": {
	".": {
	"import": "./dist/mjs/index.js",
	"require": "./dist/cjs/index.js"
	}
	},

This is essentially what is recommended here, but then here it mentions a danger in "double transpiling".

Additionally confusing, is what to target in the tsconfig:

markdown-it-plugin-template/tsconfig.json

Lines 7 to 8 in 88078b1

	"target": "es6", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 'ES2021', or 'ESNEXT'. */
	"module": "es2015", /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */

and also how babel fits in with rollup, and if @rollup/plugin-babel is actually needed (if you remove this plugin, it still builds fine at present):

markdown-it-plugin-template/rollup.config.js

Line 14 in 88078b1

babel({ babelHelpers: "bundled" }), // transpile ES6/7 code

It is of note that markdown-it itself uses the umd format (amd, cjs and iife), in its rollup config: https://github.com/markdown-it/markdown-it/blob/064d602c6890715277978af810a903ab014efc73/support/rollup.config.js#L13

Also a consideration of what is required for unpkg: unpkg/unpkg#34

Here is also a bunch of links about CommonJS vs ES Modules and building hybrid packages:

• Support Dual CommonJS/ES Module Packages with isolated state rollup/rollup#3514
• https://redfin.engineering/node-modules-at-war-why-commonjs-and-es-modules-cant-get-along-9617135eeca1
• https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html
• https://blog.logrocket.com/es-modules-in-node-today/
• https://2ality.com/2019/10/hybrid-npm-packages.html

[chrisjsewell]

@rowanc1 interested to get your opinion?

[chrisjsewell]

See also markdown-it/markdown-it#613 (comment) and nodeca/js-yaml@1b5fea8, i.e. I think markdown-it will also soon move to this duel umd + esm deployment strategy

[chrisjsewell]

Also, a related question, is how/should type files (.d.ts) be "rolled up" into a single file, see e.g. rollup-plugin-dts and Rollup your types

(plus I realised after 86e9fb3, I now have types in both dist/cjs and dist/mjs and so "types": "dist/index.d.ts" in package.json is wrong)

[rowanc1]

I have had the most experience with webpack and creating targets for consumption in browser. For most of these plugins do you see the consumption happening in the browser (through a script tag) or through node and then re-bundling at the downstream application? I suppose both might happen, but I would certainly think that most of these would be consumed through node imports? For strict node packages I have just used tsc with some basic/default configuration (I suppose this is still cjs?).

One other target I have found handy in the package.json is unpkg: pointing to the minified bundle that can be used directly in the browser.

[chrisjsewell]

cheers for the feedback

Think I have it mainly sorted now though, with: https://executablebooks.github.io/markdown-it-plugin-template/ 😄

Note, Rollup now builds umd (instead of cjs) + esm (both minified), and unpkg already loads from the main entry point in package.json, so I think unpkg is not necessary.