Error for plugins: Failed to load UMD bundle

[abjanssen]

I'm having problems using some the following no-build plugins that are available on the JBrowse website.

Both the menu-modifying plugin in the first black box here, and the myplugin.js mentioned under "importing with jbrequire here, are giving me an error that I cannot seem to fix.

If I copy and paste the literal code into a file, and refer to the file in my config files like so
{ "name": "MyPlugin", "umdLoc": { "uri": "plugins/myplugin.js" } },

I get an error

Error: Failed to load UMD bundle for MyPlugin, JBrowsePluginMyPlugin is undefined

As far as I understand, these plugins should be no-build, so I can just copy and paste the code, and they should work (after which I can modify them to my needs).

Is there something I'm doing wrong in my config file?
Do I need to configure the copied text?
Do i need a dependency of which I"m not aware.

Any help is very welcome

Thank you in advance

[cmdcolin]

Hi there,
I think there was a typo in our docs. I have now updated the page.

Notably, the "plugin name" has to match up exactly for UMD style plugins and it was not matching for our docs.

To be specific: in the config.json, where it says "name": "MyPlugin"

This has to match up with multiple places in the UMD plugin

;(function () {
  class Plugin {
    name = 'MyPlugin' <-- Here
    version = '1.0'

    install(pluginManager) { /* ... */ }

    configure(pluginManager) {}
  }

  // the plugin will be included in both the main thread and web worker, so
  // install plugin to either window or self (webworker global scope)
  ;(typeof self !== 'undefined' ? self : window).JBrowsePluginMyPlugin = // <-- AND here, with the naming JBrowsePlugin + YourPluginName
    {
      default: Plugin,
    }
})()

The UMD plugin system is quite picky in this way

However, we also support "ESM plugins" (ESM is an alternative javascript module format that is basically the modern way to do things)

They are easier to write. Notably, before 2024 browsers were a little less compatible with pure ESM plugins, but now there is broad browser compatibility

I added a section to our docs to fix and clarify these issues. We might be able to make ESM the default too because it is less picky about the naming

Updated doc page
https://jbrowse.org/jb2/docs/tutorials/no_build_plugin_tutorial

[abjanssen]

Thank you or your answer. I am still experiencing problems however.

What I have now, is the code at the bottom, and I have some observations:

• The names that you say should match, do not have to match in the plugin, as I can adapt the name under "name" to anything I want, and this won't affect any functionality. The string after "JBrowsePlugin" on the bottom of the code however, has to match the name I put in the config file under "name"
  { "name": "MyNoBuildPlugin", "umdLoc": {"uri": "plugins/MyNoBuildPlugin.js"} }

• In case the "export default class MyNoBuildPlugin" line is enabled, a white screen with the text below will display upon loading
  JBRowse error -Error: Failed to load UMD bundle for MyNoBuildPlugin, JBrowsePluginMyNoBuildPlugin is undefined

• In case the "class MyPlugin" line is enabled, JBrowse will load normally, except that every track has the same error, seemingly pointing to the 'insertMenu" in line 28. The extra menu item is present however, and i can click it to open an new widget with the citation.

Other info: i am using a macbook, JBrowse version 2.18.0, and am loading this session through "npx serve" on my command line, and my browser is Google Chrome.

;(function () {
//    comment out one of the two next lines or different behaviours. Class only ==> session loads with error, export ==> no loading error
      class MyPlugin  {
//     export default class MyNoBuildPlugin {
          name = 'MyNoBuildPlugin'
        
        install(pluginManager) {
            const { ConfigurationSchema } = pluginManager.jbrequire('@jbrowse/core/configuration',)
            const WidgetType = pluginManager.jbrequire('@jbrowse/core/pluggableElementTypes/WidgetType',)
            const { ElementId } = pluginManager.jbrequire('@jbrowse/core/util/types/mst',)
            const { types } = pluginManager.jbrequire('mobx-state-tree')
            const React = pluginManager.jbrequire('react')
            const CiteWidget = props => {
               const header = React.createElement('h1',null,'Cite this JBrowse session',)
               const content = React.createElement('p',null,`Diesh, Colin, et al. "JBrowse 2: A modular genome browser with views of synteny and structural variation. bioRxiv. 2022.`,)
               return React.createElement('div', null, [header, content])}
        pluginManager.addWidgetType(() => {
            return new WidgetType({
                name: 'CiteWidget',
                heading: 'Cite this JBrowse session',
                configSchema: ConfigurationSchema('CiteWidget', {}),
                stateModel: types.model('CiteWidget', {id: ElementId, type: types.literal('CiteWidget'),}),
                ReactComponent: CiteWidget,
          })})} 
        configure(pluginManager) {
            pluginManager.rootModel.insertMenu("Citations", 2)
            pluginManager.rootModel.appendToMenu("Citations", { label: 'Cite this JBrowse session', onClick: session => {const widget = session.addWidget('CiteWidget', 'citeWidget', {view: self,})
            session.showWidget(widget)
          },})}
  }
;(typeof self !== 'undefined' ? self : window).JBrowsePluginMyNoBuildPlugin = {default: MyPlugin,}
})()

[cmdcolin]

Sorry about that, I had made an update to our web docs but there was a bug preventing it from uploading to the live website. That should be fixed now.

I also updated the docs to be clearer and use the "ESM" syntax. You can check it out again here https://jbrowse.org/jb2/docs/tutorials/no_build_plugin_tutorial/

Regarding your questions

The names that you say should match, do not have to match in the plugin, as I can adapt the name under "name" to anything I want, and this won't affect any functionality. The string after "JBrowsePlugin" on the bottom of the code however, has to match the name I put in the config file under "name" { "name": "MyNoBuildPlugin", "umdLoc": {"uri": "plugins/MyNoBuildPlugin.js"} }

you're correct, the global variable is the most important value to match for UMD plugins. the other one is just what is displayed in the help bar. I updated the docs to use ESM plugins now though so there is not even a need for the global variable to match anymore, which hopefully helps a bit

In case the "export default class MyNoBuildPlugin" line is enabled, a white screen with the text below will display upon loading
JBRowse error -Error: Failed to load UMD bundle for MyNoBuildPlugin, JBrowsePluginMyNoBuildPlugin is undefined

That will happen because "export default class ..." is the syntax for an ESM plugin rather than a UMD plugin

In case the "class MyPlugin" line is enabled, JBrowse will load normally, except that every track has the same error, seemingly pointing to the 'insertMenu" in line 28. The extra menu item is present however, and i can click it to open an new widget with the citation.

That is a bug that I updated in our docs where you actually have to check whether pluginManager.rootModel is defined before using it. that is because the plugin is loaded on both the main thread and web worker threads and the web worker does not have a "rootModel" and the code was crashing trying to use pluginManager.rootModel.insertMenu on the web worker which crashed

these were all issues in our docs, and involve some fairly technical issues that are hard to communicate properly so thanks for reporting this and let me know if I can help clarify anything. I updated the docs to now use "ESM" plugins because they are generally easier to use than UMD so hopefully that will help future users

[abjanssen]

Thank you very much, I've now got it working!

One last (very minor) question. I wanted to incorporate icons from the mui library in the menu, much like the exclamation and question mark in the current "Help" menu. From what I understand, JBrowse uses the MUI library, and reexports parts of it through the PluginManager for use in plugins.

The email icon can be loaded through through import EmailIcon from '@mui/icons-material/Email'; according to the MUI website.
The icons-material part however, does not seem to be exported in PluginManager, only @mui/material/utils and @material-ui/core/utils are exported as MUIUtils in the the modules.tsx file (packages/core/ReExports/modules.tsx).

Am I right when I say that I cannot access the icons currently? Or is there another way to get there?

Looking forward to your input on this, thank you in advance.

[cmdcolin]

Am I right when I say that I cannot access the icons currently? Or is there another way to get there?

no-build plugins can not access the mui icons library. We do not re-export the entire set of MUI icons which was a conscious decision because it would make our bundle size very large to do so.

If you want to use a MUI icon in your plugin, i'd recommend trying the jbrowse-plugin-template because the jbrowse-plugin-template can import things from @mui/icons-material properly

an alternative for sticking with no-build plugins is to download the raw svg of an icon of interest, and copy that into your plugin. the google material icons have easy svg downloads, can also use your browsers inspector to get the @mui/icons-material version as well https://fonts.google.com/icons?selected=Material+Icons:home:&icon.size=24&icon.color=%23e8eaed