@nexeth/mermaid is a tool for generating mermaid diagrams programmatically via code. Currently, Sequence Diagram and Flowcharts are supported.
bun install @nexeth/mermaidor
yarn install @nexeth/mermaidor
npm install @nexeth/mermaidA Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order. Consult the official documentation for more information
const diagram = new SequenceDiagram();
diagram.message("Alice", "->>", "John", "Hello John, how are you?");
diagram.message("John", "-->>", "Alice", "Great!");
diagram.message("Alice", "-)", "John", "See you later!");
const render = diagram.render();
console.log(render);sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
Create a new Sequence Diagram
import { SequenceDiagram } from "@nexeth/mermaid";
const diagram = new SequenceDiagram();Each action in a sequence diagram is stored in the order it was added. This means it is not possible to remove an item once it has been added. If you wish to start again with the same diagram instance, calling reset will reset the diagram
const diagram = new SequenceDiagram("Test");
// ...
diagram.reset();To return the rendered diagram, call the render function. Note that this only returns the correctly formatted sequence diagram and does not generate the diagram itself.
const diagram = new SequenceDiagram();
const output = diagram.render();A title is optional for a sequence diagram. It can be passed into the constructor for a new diagram
const diagram = new SequenceDiagram({ title: "This is a title" });This will render
sequenceDiagram
title This is a title
The participants or actors in a sequence diagram represent entities that interact with each other. You can define participants in your diagram using the participant method.
To add participants to your diagram, use the participant method. Participants are added in the order they appear in your code. You can also specify additional options like type, alias, and create for each participant.
const diagram = new SequenceDiagram();
// Adding participants
diagram
.participant("Alice")
.participant("Bob", { type: "actor" }) // Specify type as "actor"
.participant("Charlie", { alias: "C" }) // Add an alias
.participant("David", { create: true }); // Create participant
const output = diagram.render();This will render participants in the diagram following the order they were added, along with their specified options:
sequenceDiagram
participant Alice
actor Bob
participant Charlie as C
create participant David
You can also mark participants for destruction in the diagram. To do this, use the destroyParticipant method. Destroyed participants will be indicated with the destroy keyword in the diagram.
const diagram = new SequenceDiagram();
// Adding participants
diagram.participant("Alice");
diagram.destroyParticipant("Bob"); // Mark participant for destruction
diagram.participant("Charlie");
const output = diagram.render();This will render participants with the "destroyed" status in the diagram:
sequenceDiagram
participant Alice
destroy Bob
participant Charlie
@nexeth/mermaid supports method chaining, making it easier to create your sequence diagrams more compactly. You can chain multiple method calls together to define your diagram. For example:
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.participant("Bob")
.message("Alice", "->", "Bob", "Hello")
.participant("Charlie")
.message("Charlie", "-->", "Alice", "Hi");
const output = diagram.render();This method chaining allows you to fluently define your sequence diagrams in a more concise manner.
Messages in a sequence diagram represent interactions or communication between participants. You can add messages using the message method. Messages can have various arrow types and optional activation and deactivation.
To add messages to your diagram, use the message method. You can specify the sender, receiver, arrow type, and message text. Additionally, you can include activation and deactivation options for messages.
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.participant("Bob")
.message("Alice", "->", "Bob", "Hello")
.message("Bob", "-->", "Alice", "Hi", { activate: true })
.message("Alice", "-x", "Bob", "Bye", { deactivate: true });
const output = diagram.render();This will render messages in the diagram with the specified arrows, activation, and deactivation:
sequenceDiagram
participant Alice
participant Bob
Alice->Bob: Hello
activate Bob
Alice-xBob: Bye
Boxes allow you to group actors or participants within a vertical box in your diagram. You can create boxes using the box method.
To add a box to your diagram, use the box method. You can specify the text content of the box and, optionally, a background color.
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.participant("Bob")
.box("Group A")
.participant("Charlie")
.participant("David")
.end()
.box("Group B", { color: "lightgray" })
.participant("Eve")
.end();
const output = diagram.render();This will render boxes in the diagram, visually grouping participants and actors:
sequenceDiagram
participant Alice
participant Bob
Box lightgray Group A
participant Charlie
participant David
end
Box lightgray Group B
participant Eve
end
You can specify activation and deactivation of participants using the activate and deactivate methods.
To activate a participant, use the activate method and specify the participant's name. This will visually indicate the participant's activation.
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.participant("Bob")
.activate("Alice")
.message("Alice", "->", "Bob", "Hello")
.message("Bob", "-->", "Alice", "Hi")
.deactivate("Alice");
const output = diagram.render();This will render activations and deactivations in the diagram:
sequenceDiagram
participant Alice
participant Bob
activate Alice
Alice->Bob: Hello
Bob-->>Alice: Hi
deactivate Alice
Notes are annotations that provide additional information about specific interactions in the diagram. You can add notes using the note methods, such as note, noteOver, noteLeftOf, and noteRightOf.
To add notes to your diagram, use the appropriate note method along with the location, participants, and note text.
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.participant("Bob")
.message("Alice", "->", "Bob", "Hello")
.noteOver(["Alice", "Bob"], "Important note here")
.message("Bob", "-->", "Alice", "Hi");
const output = diagram.render();This will render notes in the diagram, positioned according to the specified location:
sequenceDiagram
participant Alice
participant Bob
Alice->Bob: Hello
note over Alice, Bob: Important note here
Bob-->>Alice: Hi
Regions in a sequence diagram allow you to define loops, alternatives, and other specialized groupings. You can create regions using methods like loop, alt, else, opt, par, critical, and, and break.
To add regions to your diagram, use the corresponding region method and specify the text content for the region.
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.participant("Bob")
.loop("Repeat three times")
.message("Alice", "->", "Bob", "Hello")
.message("Bob", "-->", "Alice", "Hi")
.end()
.alt("Choice A")
.message("Alice", "-x", "Bob", "Bye")
.else("Choice B")
.message("Alice", "-->", "Bob", "Later")
.opt("Optional")
.message("Alice", "->>", "Bob", "Maybe")
.par("Parallel")
.message("Alice", "-->>", "Bob", "Hello")
.critical("Critical")
.message("Alice", "-->", "Bob", "Important")
.and("And")
.message("Alice", "->>", "Bob", "Hello")
.break("Break")
.message("Alice", "-->>", "Bob", "Goodbye");
const output = diagram.render();This will render regions in the diagram, visually grouping interactions:
sequenceDiagram
participant Alice
participant Bob
loop Repeat three times
Alice->Bob: Hello
Bob-->>Alice: Hi
end
alt Choice A
Alice-xBob: Bye
else Choice B
Alice-->Bob: Later
opt Optional
Alice->>Bob: Maybe
par Parallel
Alice-->>Bob: Hello
critical Critical
Alice-->Bob: Important
and And
Alice->>Bob: Hello
break Break
Alice-->>Bob: Goodbye
Rectangles in a sequence diagram represent a rectangular shape with a specified color. You can add rectangles using the rect method.
To add rectangles to your diagram, use the rect method and specify the color of the rectangle.
const diagram = new SequenceDiagram();
diagram.participant("Alice").rect("lightblue").participant("Bob").end();
const output = diagram.render();This will render rectangles in the diagram with the specified color:
sequenceDiagram
participant Alice
rect lightblue
participant Bob
end
Comments in a sequence diagram provide additional information or annotations. You can add comments using the comment method.
To add comments to your diagram, use the comment method and specify the comment text.
const diagram = new SequenceDiagram();
diagram
.participant("Alice")
.message("Alice", "->", "Bob", "Hello")
.comment("This is a comment")
.message("Bob", "-->", "Alice", "Hi");
const output = diagram.render();This will render comments in the diagram:
sequenceDiagram
participant Alice
Alice->Bob: Hello
%% This is a comment
Bob-->>Alice: Hi
Custom elements allow you to include arbitrary text or custom Mermaid syntax in your diagram. You can add custom elements using the custom method.
To add custom elements to your diagram, use the custom method and specify the custom text.
const diagram = new SequenceDiagram();
diagram.participant("Alice").custom("%% This is a custom element").message("Alice", "->", "Bob", "Hello");
const output = diagram.render();This will render custom elements in the diagram:
sequenceDiagram
participant Alice
%% This is a custom element
Alice->Bob: Hello
To obtain the final rendered sequence diagram, call the render method on your diagram instance. This will return the correctly formatted sequence diagram as a string.
const diagram = new SequenceDiagram();
// Add elements to the diagram...
const renderedDiagram = diagram.render();
console.log(renderedDiagram);This will log the generated sequence diagram text to the console.
A Flowchart diagram is a graphical representation of a process, showing the steps as boxes of various shapes and connecting them with arrows. Consult the official documentation for more information.
import { Flowchart } from "@nexeth/mermaid";
const chart = new Flowchart({ title: "My Flowchart", flowchartType: "TD" });
chart.node("A", "Start").node("B", "Process").link("A", "-->", "B", "Yes").node("C", "End").link("B", "-->", "C");
const render = chart.render();flowchart TD
A[Start]
B[Process]
A-->|Yes|B
B-->C[End]
flowchart TD
A[Start]
B[Process]
A-->|Yes|B
B-->C[End]
Create a new Flowchart diagram
import { Flowchart } from "@nexeth/mermaid";
const chart = new Flowchart({ title: "My Flowchart", flowchartType: "TD" });Nodes represent steps or processes in your flowchart. You can define nodes in your diagram using the node method.
To add nodes to your flowchart, use the node method. Nodes are added in the order they appear in your code. You can specify text and shape for each node.
const chart = new Flowchart();
// Adding nodes
chart.node("A", "Start").node("B", "Process", "stadium").node("C", "End", "round");
const output = chart.render();This will render nodes in the diagram following the order they were added, along with their specified text and shape:
flowchart TD
A[Start]
B([Process])
C[End]
Links represent connections between nodes in your flowchart. You can add links using the link method.
To add links to your flowchart, use the link method. You can specify the source node, link type, target node, and optional link text.
const chart = new Flowchart();
// Adding nodes
chart.node("A", "Start").node("B", "Process").node("C", "End").link("A", "-->", "B", "Yes").link("B", "-->", "C");
const output = chart.render();This will render links in the diagram with the specified link type and text:
flowchart TD
A[Start]
B[Process]
A-->'Yes'|Yes|B
B-->C[End]
Subgraphs allow you to group nodes and links within a separate box in your flowchart. You can create subgraphs using the subgraph method.
To add a subgraph to your flowchart, use the subgraph method. You can specify the subgraph's ID and an optional title.
const chart = new Flowchart();
// Adding subgraph
chart.subgraph("Group A", "Group Title").node("A", "Start").node("B", "Process").end().node("C", "End");
const output = chart.render();This will render subgraphs in the diagram, visually grouping nodes and links:
flowchart TD
subgraph Group A[Group Title]
A[Start]
B[Process]
end
C[End]
Direction
You can specify the direction of your subgraph using the direction method.
const chart = new Flowchart();
// Adding subgraph
chart.subgraph("Group A", "Group Title").direction("LR").node("A", "Start").node("B", "Process").end().node("C", "End");
const output = chart.render();Comments in a flowchart provide additional information or annotations. You can add comments using the comment method.
To add comments to your flowchart, use the comment method and specify the comment text.
const chart = new Flowchart();
chart.node("A", "Start").node("B", "Process").comment("This is a comment").node("C", "End");
const output = chart.render();This will render comments in the diagram:
flowchart TD
A[Start]
B[Process]
%% This is a comment
C[End]
To obtain the final rendered flowchart, call the render method on your chart instance. This will return the correctly formatted flowchart as a string.
const chart = new Flowchart();
// Add elements to the flowchart...
const renderedChart = chart.render();
console.log(renderedChart);This will log the generated flowchart text to the console.
That's it! You should now be able to create complex sequence diagrams programmatically using @nexeth/mermaid. Explore the official Mermaid documentation for more advanced features and customization options.