cytoscape.js
cytoscape.js copied to clipboard
cytoscape
Improving ESM support and documentation, esp. for browsers
Update the package to better support ESM, especially in the browser, by default:
- [x] Include external dependencies in the regular
.esm.jsbuild, which removes the need for specifying import maps. They are small dependencies, and other builds already include them (like the UMD build). - [x] Update
package.jsonto includemodule, pointing to the ESM build. - [x] Include the
exportskey inpackage.jsonforimportandrequire.
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/[email protected]/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 https://github.com/qiao/heap.js/pull/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
importmapw/o heap and also change your_esmfile 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.
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.
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 https://github.com/cytoscape/cytoscape.js/issues/3217#issuecomment-1919183677, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHHLRFOI6FGSUR7LVRN4M3DYRJGNPAVCNFSM6AAAAABCSEJUMCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMJZGE4DGNRXG4 . You are receiving this because you authored the thread.Message ID: @.***>
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!
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.
![stale[bot] avatar](https://avatars.githubusercontent.com/in/1724?v=4 "Published by a pub.dev verified publisher"){kind=small}
Tested package.json updates from 9bd7a73 in Enrichment Map:
https://github.com/cytoscape/enrichment-map-webapp
cd cytoscapegit checkout unstable && git pullnpm linkcd ../enrichment-map-webappnpm link cytoscapenpm run watch- Go to
http://localhost:3000in 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.
@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.
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 [email protected]:cytoscape/cytoscape.js.gitcd cytoscape.jsgit checkout unstable && git pullnpm linkcd ../my-appnpm link cytoscapenpm run watchornpm run devornpm run build-- however you do it- Verify your app builds and works
I've updated the
distfiles on the unstable branch: https://github.com/cytoscape/cytoscape.js/blob/4372a14065ed26aa781f3b563d5907b9fee80054/dist/cytoscape.esm.jsThat should make your testing a bit simpler. You can verify that the ESM file linked above doesn't use any
importstatements whatsoever.Steps:
git checkout [email protected]:cytoscape/cytoscape.js.gitcd cytoscape.jsgit checkout unstable && git pullnpm linkcd ../my-appnpm link cytoscapenpm run watchornpm run devornpm 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'
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.
Hey sorry, had some good news over here that I had to act on, I'm free now to do it this weekend!
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
This example should be:
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.
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
