krokidile

Krokidile is a web-based Live-Editor for Diagrams to use with Kroki.io.

• Github Repository → https://github.com/sommerfeld-io/krokidile

• DockerHub → https://hub.docker.com/r/sommerfeldio/krokidile

• Where to file issues → https://github.com/sommerfeld-io/krokidile/issues

This project is a web-based live editor for diagrams, enabling developers to see a real-time preview of their diagrams as they write the diagram code. This immediate feedback loop makes it easier to create and modify diagrams, as developers can instantly see the impact of their changes.

Diagrams are rendered with Kroki. Kroki is a tool that renders diagrams from code allowing developers to write diagrams as code.

The main advantage of using diagrams as code is that it allows for version control, collaboration, and automation, just like any other piece of code in your repository

Krokidile provides a web-based live editor for diagrams, enabling developers to see a real-time preview of their diagrams as they write the code. This immediate feedback loop makes it easier to create and modify diagrams, as developers can instantly see the impact of their changes.

Features

• Real-time preview of diagrams based on diagram code

• Export diagrams as PNG or SVG image

• Save the diagram code as a file

• Supported diagram types

  • BlockDiag

  • Ditaa

  • C4 with PlantUML

  • Erd (Entity-Relationship Diagram)

  • Mermaid

  • PlantUML

  • RackDiag

  • Structurizr

Code editor behavior

When the diagram type is changed the editor is populated with an example code of the selected diagram type. However, when code is changed by the user, the code is stored in the browsers local storage and will be loaded when the page is reloaded to ensure the user does not lose their work when accidentally reloading the page.

This conflicts with displaying the example code of the selected diagram type. The code written by the user is more important than the example code. Therefore, the example code is not displayed when the user has written code.

To reset the editor content to the example code of the selected diagram type, the user can click the "Reset" button (the circle sign) next to the download buttons.

How to use

Krokidile Application

The only way to use Krokidile is to use the Docker image. The Docker image is available on Docker Hub at https://hub.docker.com/r/sommerfeldio/krokidile.

docker run --rm -p 3000:3000 sommerfeldio/krokidile:latest

This Docker compose stack starts a Krokidile instance. The Krokidile instance uses https://kroki.io to convert diagram code into images.

services:
  krokidile:
    container_name: krokidile
    image: sommerfeldio/krokidile:latest
    ports:
      - 3000:3000

Krokidile Documentation

This project also publishes a documentation. The image is available on Docker Hub at https://hub.docker.com/r/sommerfeldio/krokidile-docs.

Start with plain Docker:

docker run --rm -p 3080:3000 sommerfeldio/krokidile-docs:latest

This Docker compose stack starts a Krokidile Dococumentation website.

services:
  docs:
    container_name: krokidile-docs
    image: sommerfeldio/krokidile-docs:latest
    ports:
      - 3080:3000

Development

Consider the following steps to start developing on this project:

1. Read the Development Guide and Contribute to this Project pages.

2. Prepare the node environment with npm install.

3. Start the development server with the following command: npm run dev.

The whole Docker stack can be built and started with docker compose build && docker compose up.

To use the DevContainer, open the project in VSCode and select "Reopen in Container" from the command palette. Having Visual Studio Code (VSCode) and the Dev Container plugin installed are essential prerequisites for this development environment. Docker, of course, is also mandatory.

Components

The Frontend is built with React on top of Node.js. The Backend is a Kroki instance.

The Application consists of the following components:

+------+      +-----------------+
| User |      |  Docker Compose |
+--+---+      |                 |
   |          |   +-----------+ |      +--------+
   |          |   | Krokidile | |      | Kroki  |
   +------------->|    App    +------->| Server |
   |          |   +-----------+ |      +--------+
   |          |                 |
   |          |   +-----------+ |
   |          |   | Krokidile | |
   +------------->|   Docs    | |
              |   +-----------+ |
              +-----------------+

The Docker Compose stacks from this repo feature some additional components that are not part of the application itself but are required to run some linting tasks etc. Because they are not part of the actual application, they are not listed here.

Risks and Technical Debts

All issues labeled as risk (= some sort of risk or a technical debt) or security (= related to security issues) are tracked as Github issue and carry the respective label.

Contact

Feel free to contact me via sebastian@sommerfeld.io or visit my website https://www.sommerfeld.io.