charbugs
commented
3 years ago What about this:
- Export functions and components that are used by known public plugins to a namespace object called "lowlevel".
- Flag this object as something that can be used by plugin authors but that is unstable and likely to change.
- Tell plugin authors to update there plugins to use this object rather than doing deep imports from the module folders.
This wouldn't break any existing plugin and we could gradually decide what functions to include into or remove from this api.
jbaiter
I see a lot of implementations and plugins that import Mirador or parts of it by targeting the
esorcjsfolders directly, e.g.import Mirador from "mirador/dist/es/index. I think this is bad practice as it may break the tooling (bundling, testing and so on) in many ways. This is not to blame the people for that because we gave a lot of examples in the past that suggested doing this.Usually you compile your library code into different module formats and than give pointers in the package.json to the locations of that formats via the fields "main", "module", "browser", "exports" and some more. Than the library consumers import that code without explicitly point to a specific module format e.g.
import Mirador from 'mirador'. Now if you run tools agains that code the tools can decide what kind of modules to import. For example, Webpack prefers ES modules and expects the "browser" or "module" field to point to that modules. If this fields are not present it falls back to the "main" field that usually points to CJS modules. Jest in turn can only work with CJS modules and always targets the "main" field for that reason. If you import code from a specific module format you force the tools to use this format even if it is not appropriate.For people who simply want to run the viewer there should only be two encouraged ways: Either embedding the browser bundle via script tag from a CDN:
Or importing the constructor from an NPM package and than bundle the code:
Now if you want to create a plugin for Mirador depending on the complexity of that plugin you have to import more low level functions of Mirador. For example, here is a list of import statements from different plugins:
Actually, the redux state functions don't need to be imported that way because Mirador exports them at the top level. But all other functions and components are not exported so there is no other way than use the ES (or CJS) modules directly. If you want to use this plugins in your app you may again run in the same tooling problems describe above even if you follow the good practice of not importing ES modules directly in your own code.
Of course, we could export more functions and components to the top level and that would solve the problem. But I hesitate because that would mean to expose implementation details to the surface. So I like to know, are there any ideas how we could go about this?
Finally the whole problem is based on the fact that the plugin system has no sensible restrictions and every plugin I've seen so far is using implementation details that will change and result in plugins not working anymore without us having a chance to communicate breaking changes at new releases. So if there are ideas on that basic problem I would be happy to here them.