Add a minified all-inclusive ES6 module build #2530

TpmKranz · 2019-09-23T14:37:41Z

I've tried using cytoscape.js as an ES6 module from unpkg.com as follows:

<!doctype html>
<html><body><script type="module">
import cy from 'https://unpkg.com/cytoscape@3.10.0/dist/cytoscape.esm.js?module';
</script></body></html>

This didn't work because, as unpkg.com puts it, Package heap@0.2.6 does not contain an ES module, the same for lodash.debounce@4.0.8.

Apparently, the esm build is not for direct (bundler-less) consumption by an ES6 import.

I'd therefore kindly ask you to include such a build alongside the min one, so that folks can use either the old

<script src="[CDN]/dist/cytoscape.min.js"></script>

or the ES6

import cy from '[CDN]/dist/cytoscape.mes.js';

way of including cytoscape.js.

This PR adds such a build target and calls it cytoscape.mes.js, so as not to interfere with cytoscape.esm.js, which surely should not simply be replaced.

BTW, could someone point me towards the purpose of that esm build compared to, say, the umd build? It seems to me that at least webpack is completely oblivious to the ES6-ness of an imported module.

maxkfranz · 2019-09-23T16:26:16Z

.esm.min.js might be a clearer suffix.

BTW, could someone point me towards the purpose of that esm build compared to, say, the umd build? It seems to me that at least webpack is completely oblivious to the ES6-ness of an imported module.

If we expose the esm build as the module field, we break compatibility with existing apps. Say you have an app that uses CJS require(). All your code that calls require('cytoscape') would need to be changed to require('cytoscape').default. I consider that a breaking change, since webpack is so ubiquitous.

Until webpack fixes this issue we can't support module. It would be simple for them to fix it: Just use CJS main files when you're building CJS source, and use ESM module files only when you're building ESM source. As far as I'm aware, I don't think they're made this fix.

You have to configure webpack to alias cytoscape as cytoscape/dist/cytoscape.esm.js if you want to use the ESM dependency.

maxkfranz · 2019-09-23T16:30:51Z

Here's a relevant issue: webpack/webpack#4742

TpmKranz · 2019-09-24T14:32:18Z

.esm.min.js might be a clearer suffix.

Of course! I'd only thought of .min.esm.js and rejected that for fear of confusion with the .esm.js build, which serves a completely different purpose. This would also get rid of the necessity of a new target in package.json. MDN also mentions the .mjs extension (yielding .min.mjs), but at least in Ubuntu's nginx and mime-support packages, this extension isn't associated with the required MIME type by default, so I guess this won't be feasible.

Although .esm.min.js still leaves possibility for confusion. Say someone hits an exception and wants to investigate it in the debugger, and therefore tries to import .esm.js instead, assuming that this is the not-minified version of the .esm.min.js build, which it isn't. I've therefore enabled sourcemap generation for that build.

I've also supplemented the documentation a bit, but I'm not quite sure if it's okay to feature the ES6 module so prominently.

Here's a relevant issue: webpack/webpack#4742

Thank you very much for the explanation, now I understand why you bother with a separate esm build.

maxkfranz · 2019-09-24T17:32:53Z

Node apparently will consider all .js files as CJS and all .mjs files as ESM. But few people have ever seen .mjs files before. I think the next LTS (12) will officially support ESM (without having to use the esm package, so we'll have to consider this sometime soon.

TpmKranz · 2019-09-25T17:31:48Z

I think I found a compromise. There is an ES6 module-version of lodash.debounce and bundling heap with the esm build only adds about 1% file size. Since heap itself doesn't have any dependencies, I don't think it's critical that it remains an external dependency. This way, cytoscape can be used directly from unpkg.com as an ES6 module without a bundler and there is no confusion between the .esm.min.js and .esm.js builds, since they're basically interchangeable.

TpmKranz · 2019-09-25T18:30:27Z

Speak of the devil.

maxkfranz · 2019-09-26T17:28:21Z

documentation/md/getting-started.md


 ```html
 <script src="cytoscape.min.js"></script>
+<!--Or as an ES6 module-->


The second example should probably be in a separate code block to indicate it's a different example.

The import line shouldn't include the dist part, or people will think they can link directly to the repo.

maxkfranz · 2019-09-26T17:29:04Z

package.json

@@ -89,6 +89,7 @@
  "main": "dist/cytoscape.cjs.js",
  "unpkg": "dist/cytoscape.min.js",
  "jsdelivr": "dist/cytoscape.min.js",
+  "module": "dist/cytoscape.esm.js",


Let's not include the module field until webpack issues are resolved. The documentation could be updated to indicate that an alias needs to be used for ESM support with webpack or rollup.

maxkfranz · 2019-09-26T17:31:26Z

package.json

@@ -111,7 +112,7 @@
    "watch:build:umd": "cross-env FILE=umd SOURCEMAPS=true NODE_ENV=development rollup -c -w",
    "watch:build:cjs": "cross-env FILE=cjs SOURCEMAPS=true NODE_ENV=development rollup -c -w",
    "test": "mocha -r esm --recursive",
-    "test:build": "cross-env TEST_BUILD=true mocha",
+    "test:build": "cross-env TEST_BUILD=true mocha -r esm",


This should not include -r esm. The point of this test is to test the built bundle as consumed by node. There should be no ES modules in the tested bundle.

maxkfranz · 2019-09-26T17:32:07Z

package.json

@@ -158,6 +159,6 @@
  },
  "dependencies": {
    "heap": "^0.2.6",
-    "lodash.debounce": "^4.0.8"
+    "lodash-es": "^4.17.15"


Changing to lodash-es may cause issues with CJS apps.

maxkfranz · 2019-09-26T17:33:48Z

rollup.config.js

@@ -94,9 +113,10 @@ const configs = [
  {
    input,


This esm.js bundle should probably be left the same as it is in 3.10

This reverts commit f621514.

This reverts commit dd310c6.

TpmKranz · 2019-09-27T16:50:28Z

Thank you very much for your patience, I had gotten a little bit ahead of myself with the esm changes. Sorry!

The documentation now makes a clear distinction between the two scenarios.

maxkfranz · 2019-09-30T21:06:59Z

package.json

@@ -98,7 +98,7 @@
    "build:min": "cross-env FILE=min rollup -c",
    "clean": "rimraf build/*",
    "copyright": "node -r esm license-update",
-    "dist:copy": "cpy build/cytoscape.umd.js build/cytoscape.min.js build/cytoscape.cjs.js build/cytoscape.esm.js dist",
+    "dist:copy": "cpy build/cytoscape.umd.js build/cytoscape.min.js build/cytoscape.cjs.js build/cytoscape.esm.js build/cytoscape.esm.min.js build/cytoscape.esm.min.js.map dist",


Let's not include the map file. It's more useful for debugging than production. Many packages don't include sourcemaps for prod, e.g. https://unpkg.com/browse/lodash@4.17.15/

There should also be something like a build:esm.min script

maxkfranz · 2019-09-30T21:08:50Z

rollup.config.js

+    output: {
+      file: 'build/cytoscape.esm.min.js',
+      format: 'es',
+      sourcemap: true


Again, let's turn off the sourcemap

…ranch Ref : Add a minified all-inclusive ES6 module build #2530

Ref : Add a minified all-inclusive ES6 module build #2530

maxkfranz · 2019-10-01T19:45:10Z

@TpmKranz I've applied the changes on the unstable branch.

maxkfranz · 2019-10-01T19:45:40Z

@TpmKranz -- thanks for the PR!

Add a minified all-inclusive ES6 module build

9e4c33c

maxkfranz added this to the 3.11.0 milestone Sep 23, 2019

Better suffix, more documentation

99491ef

TpmKranz added 2 commits September 25, 2019 19:24

Use ES6-ready lodash and bundle heap with esm build

dd310c6

Don't build minimized esm build twice

5330872

Make mocha use esm

f621514

maxkfranz requested changes Sep 26, 2019

View reviewed changes

TpmKranz added 3 commits September 27, 2019 18:13

Revert "Make mocha use esm"

09dd384

This reverts commit f621514.

Revert "Use ES6-ready lodash and bundle heap with esm build"

9fcb332

This reverts commit dd310c6.

Improve “simple HTML environment” documentation

7372e2d

maxkfranz reviewed Sep 30, 2019

View reviewed changes

maxkfranz added a commit that referenced this pull request Oct 1, 2019

Cherry-pick @TpmKranz's changes re. esm-min build into the unstable b…

d6279ce

…ranch Ref : Add a minified all-inclusive ES6 module build #2530

maxkfranz added a commit that referenced this pull request Oct 1, 2019

Remove esm.min sourcemap and add build:esm.min script

7bcd7a0

Ref : Add a minified all-inclusive ES6 module build #2530

maxkfranz closed this Oct 1, 2019

Add a minified all-inclusive ES6 module build #2530

Add a minified all-inclusive ES6 module build #2530

TpmKranz commented Sep 23, 2019

maxkfranz commented Sep 23, 2019

maxkfranz commented Sep 23, 2019

TpmKranz commented Sep 24, 2019

maxkfranz commented Sep 24, 2019

TpmKranz commented Sep 25, 2019

TpmKranz commented Sep 25, 2019

maxkfranz Sep 26, 2019

maxkfranz Sep 26, 2019

maxkfranz Sep 26, 2019

maxkfranz Sep 26, 2019

maxkfranz Sep 26, 2019

TpmKranz commented Sep 27, 2019

maxkfranz Sep 30, 2019

maxkfranz Sep 30, 2019

maxkfranz Sep 30, 2019

maxkfranz commented Oct 1, 2019

maxkfranz commented Oct 1, 2019

Add a minified all-inclusive ES6 module build #2530

Add a minified all-inclusive ES6 module build #2530

Conversation

TpmKranz commented Sep 23, 2019

maxkfranz commented Sep 23, 2019

maxkfranz commented Sep 23, 2019

TpmKranz commented Sep 24, 2019

maxkfranz commented Sep 24, 2019

TpmKranz commented Sep 25, 2019

TpmKranz commented Sep 25, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TpmKranz commented Sep 27, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maxkfranz commented Oct 1, 2019

maxkfranz commented Oct 1, 2019