entity-relationship diagram

Initial Thoughts on Mermaid JS, an open-source tool for Software Diagram as Code

2023/04/02

For the longest time, I’ve been annoyed at not having access to $$$ Microsoft Visio or Visual Paradigm for creating software diagrams like Class Diagrams or Entity-Relationship Diagrams. Some IDEs have built-in plug-ins that can generate diagrams based on existing code, but they tend to contain other information that are not so important when I want to highlight certain items only. So, I usually end up using Microsoft Excel or Microsoft PowerPoint.

I decided to test Mermaid JS (version 10.0.2, as of 2023-04-02), a JavaScript-based open-source tool for “Software Diagram as Code”: https://mermaid.js.org/. It’s not really limited to software diagrams, since it can also support other diagrams like Gantt Chart, Pie Chart, Mind Map, etc. For the code part, Mermaid JS diagrams are created using Markdown, a markup language.

Below is an example of an Entity-Relationship Diagram I created using SAP Commerce Cloud entities related to Product data models. This is using IntelliJ IDEA with the Mermaid plug-in installed. The ArjanCodes video I share later uses Visual Studio Code IDE. The IDE shows the code at the left side, which is automatically rendered at the right side when the changes are saved.

After watching a YouTube video by ArjanCodes – Mermaid JS: Finally There’s A Great UML & Diagram Drawing Tool – I share my initial thoughts:

Mermaid JS looks good enough for the basics I need: Class Diagram, Entity-Relationship Diagram, Sequence Diagram, and Flow Chart.
It could be a challenge to use if you’re used to paragraph-like pseudocode. So, you’re better off with Microsft Word or Microsoft Excel. We’ve all been there, right?
Sequence Diagrams for complex scenarios could be challenging (again) and look messy and difficult to refactor. I imagine you’d have to visualize the entire flow in your mind first before you write the design down, since you cannot visually create the items or relationships you need at the start.
I’m not OCD, but when I used Microsft Excel, I’d spend some time resizing, realigning, or rearranging items in diagrams. Mermaid JS does this for you automatically. But, that’s also it’s downside, since you can’t reposition the boxes to exactly where you want them.
The custom Markdown syntax can be confusing, since different diagrams can have different syntax. On the bright side, it’s all code/text. So, you can push the code to your source code repository. Other repositories like GitHub have features / plug-ins that can visually render these code. Neat.

Overall, Mermaid JS looks promising, and I’ll be exploring it more soon. Plus, it’s FREE!

Other references: