Ability to import only mermaidAPI

[knsv]

This is related to: #617, #813

The idea with having both mermaidAPI and mermaid are the separation of the actual bootstrapping part of mermaid with the diagram rendering. With bootstrapping I mean the code in mermaid for checking if the document is loaded, finding the elements to render etc. The rendering code is in mermaidApi, the default bootstrapping that looks for elements with the classname mermaid might not be suitable in all integrations.

The ability to import only mermaidAPI and not mermaid was lost when migrating to webpack and es6. This should be re-enabled.

If an integrator wants to do their own bootstrapping as in some other mechanism for rendering diagrams he or she is free to do so via the API. This is currently not obvious from the docs.

An example of usage for the mermaidAPI is available in this example repo:
https://github.com/mermaid-js/api-integration-ex

In the example the mermaidAPI is fetched from mermaid. After this issue is resolved it will be possible to skip mermaid and only import mermaidAPI.

[jrdavismaine]

I was able to create a standalone mermaidAPI.js file by changing the below webpack.config.base.js objects. After running npm run build, mermaid.js and mermaidAPI.js were present in the dist folder.

entry

entry: {
    mermaid: './src/mermaid.js',
    mermaidAPI: './src/mermaidAPI.js'
},

output

output: {
    path: path.join(__dirname, './dist/'),
    filename: '[name].js',
    library: '[name]',
    libraryTarget: 'umd',
    libraryExport: 'default'
},

The below code seems to work. So creating a standalone mermaidAPI.js file is indeed possible. Not sure the above changes are the most elegant solution though.

<div id="graphDiv"></div>
<script type='text/javascript' src="./dist/mermaidAPI.js"></script>
<script>
    mermaidAPI.initialize({
        startOnLoad:false
    });
    (function(){
        // Example of using the API
        var element = document.querySelector("#graphDiv");
        var insertSvg = function(svgCode, bindFunctions){
            console.log(svgCode);
            element.innerHTML = svgCode;
        };
        var graphDefinition = 'graph TB\na-->b';
        var graph = mermaidAPI.render('graphDiv', graphDefinition, insertSvg);
    })();
</script>

[klemmchr]

Imo mermaid should ship as a single file where you can import either mermaid or mermaidAPI. Having two separate files means redundant code.

[knsv]

I think that with the config above a mermaid.js and a mermaidAPI.js is generated under dist. The mermaid.js will contain mermaid + mermaidApi thanks to webpack and mermaidApi will only contain mermaidApi.

When a consumer of mermaid creates a bundle with webpack or similar redundant code will be excluded by the bundler so I think this would work.

Thanks @jdavis61. I will test this with webpack and see how it behaves. Do you want to create pull request, if not I can copy from here and fiddle around a bit with it.

[jrdavismaine]

Hi @knsv, I have been trying to implement @chris579's feedback but have not been able to configure webpack to allow mermaid to ship as a single file and import both mermaidAPI and mermaid.

I will keep researching and hopefully open a PR that implements his feedback. If I cannot figure out a solution, I will open a PR with the above webpack config + some cypress tests as you suggested.

If you have a solution feel free to open a PR as well, do not wait for me.

[knsv]

I have been trying this out and I am starting to hesitate a little. The solution works and when using webpack it is able to to bundle only the API part of mermaid and not the bootstrapping parts.

Whats makes me hesitate a bit is that the bootstrapping is quite small. The sizes (uncompressed):

• mermaid.js 3669628
• mermaidAPI.js 3561824

Is it worth the additional complexity for the relative small change in file size?
What is easiest for the user, turning off startOnLoad in the config and using mermaid.render or importing mermaid/mermaidAPI and using that render?

Opinions are appreciated.

[jrdavismaine]

@knsv I personally think allowing mermaidAPI to be imported on its own unnecessary. Or maybe not worth the effort to implement, e.g. doubling the size of the mermaid CDN.

Just my opinion, I am sure there is a valid use case for allowing mermaidAPI to be imported on its own. I just cannot think of one. I used the below code in a project and it works perfectly.

function createFlowChart(graphText, graphIDAttribute, graphContainerIdAttribute) {
    const config = getConfig()
    mermaid.initialize(config)
    mermaid.render(graphIDAttribute, graphText, null, 
    document.getElementById(graphContainerIdAttribute))
}

This warning does not make any sense to me, though I am not a mermaid.js expert. Again I am sure there is a good reason for this.

Warning This type of integration is deprecated. Instead the preferred way of handling more complex integration is to use the mermaidAPI instead.

I will try to figure out how to import mermaidAPI standalone without doubling the size of the CDN. It would be cool to figure out a solution to this problem.

Cheers!

[klemmchr]

Well, I think we should favor into exposing all mermaidAPI methods in the mermaid class. This way we avoid two public apis (which is a pro argument imo) and users can still use low level stuff from mermaidAPI. Regarding the current state, I also don't see a reason to have two public apis nor two generated js files.

[jrdavismaine]

I will try to figure out how to import mermaidAPI standalone without doubling the size of the CDN. It would be cool to figure out a solution to this problem.

Hi @knsv , as far as I know, the only way to allow mermaid and mermaidAPI to be imported standalone is to use the output object I created in my first post. In webpack terminology this is called a multi-part-library.

Unfortunately I cannot think of any other way to implement this request using webpack. I guess the only other way to do this is to implement chris579's suggestion.

Anyways best of luck, thank you for creating such an awesome online flowchart library!

-- MISC
Maybe the answer can be found in one of the examples?
https://github.com/webpack/webpack/tree/master/examples/
https://github.com/webpack/webpack/tree/master/examples/multi-part-library

Cheers!

[sidharthv96]

mermaidAPI can be accessed via the mermaid object.
One single file keeps everything simple.

Please reopen is there is a clear usecase.