Unify HTML template and React component

[fmvilas]

On This Page

• Summary
  • Problem Overview
  • Solution Overview
  • Positive Side-Effects
• Solution guidelines
• Boundaries
  • Don’t go too far refactoring the React component
  • Don't support theming
  • Watch out for those little details
  • Watch out for template parameters
• Long-Term Vision

Summary

Problem Overview

We're currently maintaining two HTML documentation views: the HTML template and the React component.

Solution Overview

Improve the React component so it matches the features and look & feel of the HTML template. Once it's done, make the HTML template use the React component to generate the HTML output.

Positive Side-Effects

1. Less code to maintain.
2. Studio is using React so we should be able to render the docs on the client side. That will allow us to get rid of the expensive servers we have for the Playground right now and host it for free on Netlify or similar.

Solution guidelines

While this task may sound easy, there are a bunch of small features/details that are not present in the React component:

1. It doesn't offer a sidebar navigation.
2. It's using tables to show information. We already saw in the initial versions of the HTML template that it doesn't scale well as usually most of the fields appear empty.
3. It has a section of messages and schemas but it only shows the ones under components.
4. It's using the term "topics" instead of "channels".
5. It's not using Tailwind.
6. It's not working with AsyncAPI 2.0.0 (or I can't make it work)
7. It's merging objects when it finds allOf, which is an incorrect behavior.
8. It's not handling additionalItems.

We should make sure these features are present in the React component. Otherwise, people will be losing features with the switch from the HTML template to React.

When it comes to making the HTML template render the React component, my suggestion is that we have a look at the following ReactDOMServer and ReactDOM methods:

• ReactDOMServer.renderToNodeStream()
• ReactDOM.hydrate()

I found this article very helpful: https://dev.to/marvelouswololo/how-to-server-side-render-react-hydrate-it-on-the-client-and-combine-client-and-server-routes-1a3p

One possible solution here is to make the HTML template an empty template with a generate:after hook where we do all the rendering process.

Boundaries

Don’t go too far refactoring the React component

Don't worry about the architecture of the React component. We'll dedicate time converting it to a UI library in the next cycles.

Don't support theming

Let's forget about the theme feature of the component for now. It will only have a single "theme" and it's the one matching the styles of the HTML template. We'll add support for themes on the future UI library instead.

Watch out for those little details

Those that may be present on the HTML template but not on the React component.

Watch out for template parameters

The HTML template supports some parameters like singleFile, baseHref, version, sidebarOrganization, and others. We should make sure they still work.

Long-Term Vision

The idea is to start moving towards a single source of truth for our UI components. This is just the first step before we start working on the UI library which will offer many components instead of just a single big one.

In the near future, we'll also have our own design system for those who want to create custom AsyncAPI components that still match our look & feel.