Unify HTML template and React component

[fmvilas]

Reason/Context

Currently, we're maintaining this HTML template and the React component. They both serve the same purpose, displaying docs in a browser.

It would be great to unify both somehow so we don't have to maintain the two. Here are my proposals:

Generate the HTML template from the React component using Server-Side Rendering (SSR)

React provides a library called ReactDOMServer that allows us to render a React component using Node.js and get the result as a string. See renderToString().

The HTML template could be an empty template that only contains a generate:after hook, where we run this process of generating the HTML from the React component and save it into an index.html file. This would be enough to render static markup but the elements will not be interactive (i.e., they would not respond to mouse events, etc.). Luckily, we have the ReactDOM.hydrate() method that will make markup interactive.

Generate the HTML template from the React component using client-side bundle.js

This method would be the simplest to accomplish. We generate a bundle.js file from the React component and use it straight in our index.html. We just need to "embed" the asyncapi.yaml file in the index.html file when calling the "render" method. Not as difficult as it may sound.

Downsides I can foresee are:

1. Bundle size is going to be unnecessarily big? The bundle.js file will have React and all the dependencies included. They will be loaded in the browser every time we visit the docs.
2. External $ref references will be resolved from the browser every time the docs are opened. The browser may not have enough permissions to get the files or the servers may be unreachable.

---

I'm all in with the first solution. I'm not yet sure how hydrate works but seems to be powering Next.js, Gatsby, and others; so it should be possible to make markup interactive, and hopefully we don't have to include React and other dependencies in the JS file the browser has to load every time.

Of course, both solutions require us to make React component as good as the HTML template :)

[derberg]

From my perspective we for sure need to make sure that react component should be usable without react to get wider adoption. We could produce official bundle, similar to the one created by the community and described here -> asyncapi/spec#391

for the html template replacement, I like the idea to do it as Nextjs and Gatsby are doing with react when you use they to generate static websites. Regarding bundle.js:

External $ref references will be resolved from the browser every time the docs are opened. The browser may not have enough permissions to get the files or the servers may be unreachable.

this should not be a problem as we resolve refs first in the generator using parser

"embed" the asyncapi.yaml

we would just make it possible to render spec from inline spec, so template would be super simple, would just inject the asyncapi document available in nunjucks by default

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[magicmatatjahu]

Related issue in React component - asyncapi/asyncapi-react#265