Improving ESM support and documentation, esp. for browsers #3217

ayjayt · 2024-01-31T00:09:47Z

Update the package to better support ESM, especially in the browser, by default:

Include external dependencies in the regular .esm.js build, which removes the need for specifying import maps. They are small dependencies, and other builds already include them (like the UMD build).
Update package.json to include module, pointing to the ESM build.
Include the exports key in package.json for import and require.

The package.json updates for ESM will work in the browser, in bundlers like Webpack, and in Node, because it doesn't have any external dependencies.

Original post follows:

I made it work. This about using cytoscape esm or ANY esm in the browser WITHOUT bundling, which in cytoscape is currently brokenish.

You have 2 dependencies, 1 of which, lodash, you split into a few.

Browser only supports ESM w/ relative imports because they haven't figured out how they want to handle non-URI indicators like import { myFunc } as "SomeWebGlobalModule".

So you use an inline <script type=importmap> in <head>, mine looks like this:

{
  "imports": {
      "lodash":"https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/lodash.min.js",
      "heap": "./js/vendor/heap.mjs"
   }
}

(no src available, only one declaration, first thing).

I also had to change the cytoscape ESM file:

import { default as Heap } from 'heap';
import { debounce, get, set, toPath } from 'lodash';

Now, with esm, because of static analysis, you don't need to split lodash off into separate things to make a bundler understand not to use the whole library. It can shake the tree. The network doesn't shake trees tho, and so we pull the whole file over the network. I wanted to use a CDN, and I didn't find esm versions of the individual methods, only the whole lodash.

Heap is an unmaintained library, 3 years now. Its also like 80 lines of code and you should probably just absorb it. I did fix it to support esm qiao/heap.js#34 (there is no way to import a cjs-only package except in node or webpack or rollup or etc which understand require because the import is effectively transpiled to require since that's all it supports.)

My suggestions for better supporting ESM:

Absorb heap's few lines of code (ultimately reducing your size because no glue) or publish the updated package yourself. It's unmaintained.
Then give people my importmap w/o heap and also change your _esm file for my combined import.
or
Or someone publish on CDN an esm version of the lodash individual packages and add each one to importmap.

Hi @TpmKranz and @maxkfranz . Just @ ing you because I see you on the git-blame for how to use ESM w/ browser :-)

Thanks!

ps. thinking about making a pull request to npm like npm install --web which could solve some of these issues.

The text was updated successfully, but these errors were encountered:

maxkfranz · 2024-01-31T14:12:27Z

Good analysis.

What about absorbing all the dependencies?

They're small and it would simplify the bundles -- i.e. '.min.js' would be the same as '.js' w.r.t. dependencies. You also wouldn't need to specify a mapping.

PRs welcome.

ayjayt · 2024-01-31T14:15:34Z

I'm working on transpiling dagre right now to ESM. It's cytoscape --> dagre-cytoscape --> dagre --> graphlib. I'm almost done with graphlib. Why would min currently be different then non-min for deps? Something else for me to investigate...

…

On Wed, Jan 31, 2024 at 9:12 AM Max Franz ***@***.***> wrote: Good analysis. What about absorbing all the dependencies? They're small and it would simplify the bundles -- i.e. '.min.js' would be the same as '.js' w.r.t. dependencies. You also wouldn't need to specify a mapping. PRs welcome. — Reply to this email directly, view it on GitHub <#3217 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHHLRFOI6FGSUR7LVRN4M3DYRJGNPAVCNFSM6AAAAABCSEJUMCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMJZGE4DGNRXG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

maxkfranz · 2024-01-31T14:24:36Z

The min builds include the dependencies within the one file.

ayjayt · 2024-01-31T14:32:09Z

Oh so even in ESM you bundle them 🤔. I'm not sure I would expect that behavior as an end-user.

Resolved by your suggestion though! I will see maybe if I get around to it. Thanks!

stale · 2024-02-16T00:33:06Z

This issue has been automatically marked as stale, because it has not had activity within the past 14 days. It will be closed if no further activity occurs within the next 7 days. If a feature request is important to you, please consider making a pull request. Thank you for your contributions.

Ref: - Improving ESM support and documentation, esp. for browsers #3217 - Change rollup.config to bundle deps in esm.js #3221

maxkfranz · 2024-02-20T21:52:00Z

Tested package.json updates from 9bd7a73 in Enrichment Map:

https://github.com/cytoscape/enrichment-map-webapp

cd cytoscape
git checkout unstable && git pull
npm link
cd ../enrichment-map-webapp
npm link cytoscape
npm run watch
Go to http://localhost:3000 in the browser
Run the demo query

@mikekucera, @chrtannus -- this is an important but potentially disruptive change. Would you test the steps above and confirm that the EM build still works for you? I'd like to confirm that this is working on machines other than my Macbook.

maxkfranz · 2024-02-20T21:53:16Z

@ayjayt, would you also confirm the steps in the previous comment -- replacing enrichment-map-webapp with your own project that uses Cytoscape with a build system, like Webpack or Rollup.

ayjayt · 2024-02-20T21:57:58Z

I can do it before Monday

- Improving ESM support and documentation, esp. for browsers #3217 - Adding exports map in package.json #3218

maxkfranz · 2024-02-27T14:45:10Z

I've updated the dist files on the unstable branch: https://github.com/cytoscape/cytoscape.js/blob/4372a14065ed26aa781f3b563d5907b9fee80054/dist/cytoscape.esm.js

That should make your testing a bit simpler. You can verify that the ESM file linked above doesn't use any import statements whatsoever.

Steps:

git checkout git@github.com:cytoscape/cytoscape.js.git
cd cytoscape.js
git checkout unstable && git pull
npm link
cd ../my-app
npm link cytoscape
npm run watch or npm run dev or npm run build -- however you do it
Verify your app builds and works

maxkfranz · 2024-03-06T19:27:34Z

I've updated the dist files on the unstable branch: https://github.com/cytoscape/cytoscape.js/blob/4372a14065ed26aa781f3b563d5907b9fee80054/dist/cytoscape.esm.js

That should make your testing a bit simpler. You can verify that the ESM file linked above doesn't use any import statements whatsoever.

Steps:

git checkout git@github.com:cytoscape/cytoscape.js.git

cd cytoscape.js

git checkout unstable && git pull

npm link

cd ../my-app

npm link cytoscape

npm run watch or npm run dev or npm run build -- however you do it

Verify your app builds and works

These steps only work if the cytoscape library is imported the proper way with ESM import. It should always look like this:

import cytoscape from 'cytoscape';

Note that only the default may be used. So this would also work:

import { default as cytoscape } from 'cytoscape'

Note: This will not work:

import * as cytoscape from 'cytoscape'

maxkfranz · 2024-03-06T19:29:59Z

Documentation updates:

https://js.cytoscape.org/#getting-started/including-cytoscape.js

<script type="module">
import cytoscape from "./cytoscape.esm.min.js";
</script>

This example should be:

<script type="module" src="cytoscape.esm.min.js"></script>

To use Cytoscape.js in an ESM environment with npm (e.g. Webpack or Node.js with the esm package):

import cytoscape from 'cytoscape';

Around this text, there should be a note that import * as cytoscape from 'cytoscape' does not work.

See cytoscape/cytoscape.js#3217 (comment)

maxkfranz · 2024-03-06T19:45:18Z

I can do it before Monday

@ayjayt, how did it go with your build?

Parts of lodash are used: - lodash/get - lodash/set - lodash/toPath - lodash/debounce `heap` is used, but it hasn't been updated in a long time. It probably never needs to be updated unless there's a serious bug. Doubtful. Ref: - Improving ESM support and documentation, esp. for browsers #3217 - Adding exports map in package.json #3218

ayjayt · 2024-03-15T17:49:54Z

Hey sorry, had some good news over here that I had to act on, I'm free now to do it this weekend!

ayjayt · 2024-03-18T07:25:08Z

My app is 100% web so that buildflow doesn't work for me- but I did set up a test project to see if I could import and dump the contents of cytoscape into stdout. So no bundler, just node.

I get the "you must include type: "module"" error- as in the unstable branch of cytoscape needs to add that to package.json. That's been my experience whenever using esm. Also, I've use type: "module" in other hybrid cjs/esm repositories and have never had it interfere with cjs, so AFAIK it's safe to add even if you're serving several ways to import that are NOT modules.

Around this text, there should be a note that import * as cytoscape from 'cytoscape' does not work.

My least favorite thing about ESM. There are some strong opinions floating around about it. But yes, easiest is to recommend NOT to use import *.

Documentation updates:

https://js.cytoscape.org/#getting-started/including-cytoscape.js
<script type="module"> import cytoscape from "./cytoscape.esm.min.js"; </script>
This example should be:
<script type="module" src="cytoscape.esm.min.js"></script>

Is this true? AFAIK there is no automatic global scope when using type="module", so cytoscape the module is inaccessible when being accessed like that, it's always the application in <script> and the module under import.

In my app, I have to use the original syntax.

ayjayt · 2024-03-18T14:13:17Z

I will note that it doesn't work if I add type="module"

Also, I've never seen exports w/ a nested ".":{} dictionary. Obviously it works, maybe that's the default value? Usually I just
"exports": { "module": "...", "require": "..."}

Nitpicking here

mikekucera · 2024-05-06T13:09:01Z

Released in 3.29.x

This was referenced Feb 2, 2024

Port cytoscape.js-dagre to ESM cytoscape/cytoscape.js-dagre#121

Closed

Change rollup.config to bundle deps in esm.js #3221

Merged

stale bot added the stale label Feb 16, 2024

maxkfranz added pinned A long-lived issue, such as a discussion and removed stale labels Feb 20, 2024

maxkfranz added this to the 3.29.0 milestone Feb 20, 2024

maxkfranz changed the title ~~On improving ESM support and documentation:~~ Improving ESM support and documentation, esp. for browsers Feb 20, 2024

maxkfranz added a commit that referenced this issue Feb 20, 2024

Update docs table for ESM build re. deps

dc2412b

Ref: - Improving ESM support and documentation, esp. for browsers #3217 - Change rollup.config to bundle deps in esm.js #3221

maxkfranz added a commit that referenced this issue Feb 20, 2024

Add exports key in package.json

9bd7a73

Ref: - Improving ESM support and documentation, esp. for browsers #3217 - Change rollup.config to bundle deps in esm.js #3221

maxkfranz assigned chrtannus, mikekucera and ayjayt Feb 20, 2024

This was referenced Feb 20, 2024

Adding exports map in package.json #3218

Closed

ESM support for extensions #3167

Closed

rollup-config-added cytoscape/cytoscape.js-automove#34

Closed

maxkfranz added a commit that referenced this issue Feb 27, 2024

Update dist files re. :

4372a14

- Improving ESM support and documentation, esp. for browsers #3217 - Adding exports map in package.json #3218

maxkfranz added a commit to cytoscape/cytoscape-web that referenced this issue Mar 6, 2024

Update cytoscape import

0703af8

See cytoscape/cytoscape.js#3217 (comment)

maxkfranz mentioned this issue Mar 6, 2024

Update cytoscape import cytoscape/cytoscape-web#139

Merged

mikekucera closed this as completed May 6, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improving ESM support and documentation, esp. for browsers #3217

Improving ESM support and documentation, esp. for browsers #3217

ayjayt commented Jan 31, 2024 •

edited by maxkfranz

Loading

maxkfranz commented Jan 31, 2024

ayjayt commented Jan 31, 2024 via email

maxkfranz commented Jan 31, 2024

ayjayt commented Jan 31, 2024

stale bot commented Feb 16, 2024

maxkfranz commented Feb 20, 2024 •

edited

Loading

maxkfranz commented Feb 20, 2024

ayjayt commented Feb 20, 2024

maxkfranz commented Feb 27, 2024 •

edited

Loading

maxkfranz commented Mar 6, 2024

maxkfranz commented Mar 6, 2024

maxkfranz commented Mar 6, 2024

ayjayt commented Mar 15, 2024

ayjayt commented Mar 18, 2024 •

edited

Loading

ayjayt commented Mar 18, 2024

mikekucera commented May 6, 2024

Improving ESM support and documentation, esp. for browsers #3217

Improving ESM support and documentation, esp. for browsers #3217

Comments

ayjayt commented Jan 31, 2024 • edited by maxkfranz Loading

maxkfranz commented Jan 31, 2024

ayjayt commented Jan 31, 2024 via email

maxkfranz commented Jan 31, 2024

ayjayt commented Jan 31, 2024

stale bot commented Feb 16, 2024

maxkfranz commented Feb 20, 2024 • edited Loading

maxkfranz commented Feb 20, 2024

ayjayt commented Feb 20, 2024

maxkfranz commented Feb 27, 2024 • edited Loading

maxkfranz commented Mar 6, 2024

maxkfranz commented Mar 6, 2024

maxkfranz commented Mar 6, 2024

ayjayt commented Mar 15, 2024

ayjayt commented Mar 18, 2024 • edited Loading

ayjayt commented Mar 18, 2024

mikekucera commented May 6, 2024

ayjayt commented Jan 31, 2024 •

edited by maxkfranz

Loading

maxkfranz commented Feb 20, 2024 •

edited

Loading

maxkfranz commented Feb 27, 2024 •

edited

Loading

ayjayt commented Mar 18, 2024 •

edited

Loading