Aller au contenu
Table des matières

kroki-playground : Un éditeur, une API et un moteur de rendu

kroki-playground est une interface Next.js pour modifier des diagrammes textuels et prévisualiser leur rendu. Sa route serveur valide le type et le format, encode la source et récupère le résultat auprès de Kroki.

Application et services API
  • Mis à jour
  • TypeScript · 98.19%
  • MIT
Composants documentés
2Explorer les modules
Documents source
2Lire les instructions
Langages du dépôtTypeScript 98.19%3

Parts calculées à partir des octets GitHub Linguist.

TypeScript98.19%
98.19%33 686 octets
JavaScript0.99%
0.99%340 octets
CSS0.82%
0.82%282 octets
Langage%Octets
TypeScript98.19%33 686
JavaScript0.99%340
CSS0.82%282

1. Aperçu

1.1. Pourquoi il existe

Suite d'expérimentation de diagrammes en TypeScript déployée sur Vercel avec rendu instantané.

1.2. Cas d’usage

Prototypage rapide de diagrammes d'architecture variés.

2. Cas d’utilisation

Un bac à sable Next.js pour écrire du code de diagramme Kroki, voir le SVG en direct et le partager par l’URL.

Diagramme de cas d’utilisation de kroki-playground : Prévisualiser un diagramme; Changer de type de diagramme; Partager ou télécharger; Rendre via l’API REST; Consulter la doc OpenAPIkroki-playgroundPrévisualiser un diagrammeChanger de type de diagrammePartager ou téléchargerRendre via l’API RESTConsulter la doc OpenAPIAuteur de diagrammesDéveloppeur client API«système»Serveur Kroki
Acteurs à gauche (personnes) et à droite (systèmes externes) ; chaque ovale est un cas d’utilisation appuyé par les fichiers cités ci-dessous.
Prévisualiser un diagramme
Auteur de diagrammesServeur Kroki

DiagramGenerator.tsx compresse la source avec encodeDiagramPayload() (pako, base64url) et charge <base>/<type>/svg/<encodé> depuis kroki.io ou NEXT_PUBLIC_KROKI_BASE_URL.

Changer de type de diagramme
Auteur de diagrammes

lib/kroki/diagramTypes.ts liste les routes Kroki (plantuml, mermaid, graphviz, d2, vega-lite…) proposées dans le sélecteur de type.

Partager ou télécharger
Auteur de diagrammes

La page inscrit ?type=…&source=… dans l’historique, peut copier l’URL Kroki dans le presse-papiers et enregistre l’image sous diagram.svg.

Rendre via l’API REST
Développeur client APIServeur Kroki

app/api/generate-diagram/route.ts accepte GET ou POST avec diagramSource, selectedDiagram et outputFormat et renvoie diagramData en base64 ; le README et openapi.yaml nomment le chemin /api/generateDiagram.

Consulter la doc OpenAPI
Développeur client API

/api-docs affiche public/openapi.yaml avec swagger-ui-react, et GET /api/openapi sert la spécification.

2.1. Scénario : Esquisser un diagramme de séquence et l’envoyer à un collègue

  1. Lancer npm install puis npm run dev et ouvrir http://localhost:3000.
  2. Choisir plantuml dans la liste des types et coller la source @startuml … @enduml.
  3. L’aperçu SVG se met à jour depuis Kroki à mesure que la source change.
  4. Copier l’URL de la page, qui porte maintenant ?type=plantuml&source=<encodé>, et l’envoyer.
  5. Cliquer sur télécharger pour enregistrer diagram.svg dans le document de conception.

Fichiers consultésREADME.mdpackage.jsoncomponents/DiagramGenerator.tsxlib/kroki/encode.tslib/kroki/diagramTypes.tsapp/api/generate-diagram/route.tsapp/api-docs/page.tsxpublic/openapi.yaml

3. Essayer

Adresse publiée dans le README du dépôt. La page s’ouvre dans un cadre isolé, seulement quand vous le demandez.

Ouvrir dans un nouvel onglet https://kroki-playground.vercel.app/

4. Démarrage

Ces commandes viennent de la documentation du dépôt. Elles n’ont pas été exécutées pendant cette revue.

Commandes déclarées dans les manifestes

4.1. package.json

dev
next dev
build
next build
start
next start
lint
eslint .
test
vitest run

5. Références du dépôt

Extraits des guides du dépôt, dans leur langue d’origine. Les liens ouvrent la version du code consultée.

Prérequis et premier essai

5.1. Requirements

README.md

  • Node.js ≥ 22 (see .nvmrc and engines in package.json). Match your Vercel project Node version to your environment.
Lire les instructions complètes ↗

5.2. Prerequisites

CONTRIBUTING.md

  • Node.js 22.x (see .nvmrc and package.json engines).
  • Optional: Dev Containers or GitHub Codespaces using .devcontainer/devcontainer.json for a consistent environment (Node 22, npm install on container create).
Lire les instructions complètes ↗
Configuration et utilisation

5.3. Environment variables

README.md

VariableWhereDescription
Lire les instructions complètes ↗

5.4. Environment variables (CONTRIBUTING.md)

CONTRIBUTING.md

VariableWhereDescription
Create a .env file locally when you need non-default Kroki URLs or other local-only settings. Never commit secrets; .env is gitignored.
Lire les instructions complètes ↗
Exploitation et dépannage

5.5. Deployment (Vercel)

README.md

The repo includes vercel.json with the Next.js framework preset and npm install / npm run build so Vercel uses the same install and build as local. Import the project in Vercel, set Node.js to match .nvmrc (22.x), and add KROKI_BASE_URL / NEXT_PUBLIC_KROKI_BASE_URL in Project → Settings → Environment Variables if you use a private Kroki instance.
Lire les instructions complètes ↗
Développement et contributions

5.6. Contributing

README.md

See CONTRIBUTING.md. Report security vulnerabilities per SECURITY.md.
Lire les instructions complètes ↗

5.7. Contributing (CONTRIBUTING.md)

CONTRIBUTING.md

Thank you for helping improve Kroki Playground. This document describes how to set up the project, what to run before opening a pull request, and how we use issues and linking.
Lire les instructions complètes ↗
Documentation source

2 documents lus parmi 2 candidats.

6. Fonctions et composants 2

Validation avant le rendu
app/api/generate-diagram/route.ts traite GET et POST avec une validation commune. encodeDiagramPayload prépare la source pour le lien Kroki. KROKI_BASE_URL choisit le service de rendu côté serveur.
Réponse et états d’échec
La route lit les octets reçus et retourne diagramUrl, diagramData en base64 et mimeType. Une erreur HTTP de Kroki devient une réponse 502 avec un code d’erreur externe, distincte d’une entrée invalide.

7. Architecture

Ouvrez un composant pour suivre ses connexions, ou explorez le diagramme complet.

Composants du système Contexte
Mermaid Diagramme interactif

Vue générale des composants et des échanges vérifiés dans le dépôt.

Vue statique de l’architecture de kroki-playground
Aperçu statique. Le diagramme interactif le remplace après le chargement de Mermaid.
flowchart LR
  n0["Éditeur de texte"]
  n1["Route API Next.js"]
  n2["Valider et encoder"]
  n3["Service Kroki configuré"]
  n4["Résultat base64 et aperçu"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 --> n0
Version texte du diagramme
  • Éditeur de texte → Route API Next.js
  • Route API Next.js → Valider et encoder
  • Valider et encoder → Service Kroki configuré
  • Service Kroki configuré → Résultat base64 et aperçu
  • Résultat base64 et aperçu → Éditeur de texte
Suivre un parcours dans le code

Suivez POST depuis req.json jusqu’à la validation et l’appel externe. La réponse contient les octets encodés de l’image, plutôt qu’un corps HTTP entièrement en SVG. Le client doit utiliser le type MIME retourné pour les afficher.

8. Dossier technique

Établi à partir du code au commit 8def712 (24 fichiers). Chaque élément vient d’une correspondance de motif dans le code: ouvrez le fichier lié avant de vous y fier.

8.1. Couches et modules

Les dossiers sont classés par couche selon leur nom, de l’interface utilisateur jusqu’à l’accès aux données. Comme le classement repose sur les noms seulement, le diagramme ne dit rien des appels entre couches.

Mermaid Vue en couches
flowchart TB
  subgraph L_presentation["Présentation"]
    direction TB
    presentation_0["components<br/>1 fichier"]
  end
  subgraph L_interface["Points d’entrée et API"]
    direction TB
    interface_0["api/generate-diagram<br/>1 fichier"]
    interface_1["api/openapi<br/>1 fichier"]
  end
  subgraph L_application["Services applicatifs"]
    direction TB
    application_0["app<br/>3 fichiers"]
    application_1["api-docs<br/>1 fichier"]
  end
  subgraph L_infrastructure["Données et infrastructure"]
    direction TB
    infrastructure_0["kroki<br/>4 fichiers"]
  end
  subgraph L_core["Source principale"]
    direction TB
    core_0["(root)<br/>5 fichiers"]
  end
  subgraph L_tests["Tests"]
    direction TB
    tests_0["kroki<br/>4 fichiers"]
    tests_1["api<br/>1 fichier"]
  end
  subgraph L_hosting["Build, CI et hébergement"]
    direction TB
    hosting_0[".github<br/>4 fichiers"]
    hosting_1["(root)<br/>1 fichier"]
    hosting_2[".devcontainer<br/>1 fichier"]
  end
  L_presentation ~~~ L_interface
  L_interface ~~~ L_application
  L_application ~~~ L_infrastructure
  L_infrastructure ~~~ L_core
  L_core ~~~ L_tests
  L_core ~~~ L_hosting
Modules et couche principale
ModuleCoucheFichiersTypesExtensions
(root)Source principale50.ts .mjs
krokiDonnées et infrastructure40.ts
appServices applicatifs30.tsx .css
api-docsServices applicatifs10.tsx
api/generate-diagramPoints d’entrée et API10.ts
api/openapiPoints d’entrée et API10.ts
componentsPrésentation10.tsx

8.2. Modèle C4

Du contexte du système aux déclarations du code. Chaque niveau conserve les limites des sources disponibles.

UML 1 · Contexte du système
1 · Contexte du système

La vue C4 la plus large : qui utilise le projet et sur quels systèmes et stockages externes il s’appuie. Rendu avec uml-mcp.

Source PlantUML
@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
System(SYS, "kroki-playground", "kroki-playground est une interface Next.js pour modifier des diagramm…")
System_Ext(E0, "Kroki")
Rel(SYS, E0, "Appelle")
@enduml
UML 2 · Conteneurs
2 · Conteneurs

Un niveau plus près : les parties qui s’exécutent séparément dans le projet, leur langage principal et le chemin des appels entre elles. Rendu avec uml-mcp.

Source PlantUML
@startuml
!include <C4/C4_Container>
LAYOUT_LEFT_RIGHT()
System_Boundary(SYS, "kroki-playground") {
  Container(APP, "kroki-playground", "TypeScript")
}
System_Ext(E0, "Kroki")
Rel(APP, E0, "Appelle")
@enduml
UML 3 · Composants et couches
3 · Composants et couches

Modules regroupés par couche du code. Les limites indiquent l’organisation, sans affirmer une isolation à l’exécution ni des appels. Rendu avec uml-mcp.

Source PlantUML
@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "kroki-playground") {
Boundary(L0, "Présentation", "layer") {
Component(M0_0, "components", "React", "1 fichiers")
}
Boundary(L1, "Points d’entrée et API", "layer") {
Component(M1_0, "api/generate-diagram", "TypeScript", "1 fichiers")
Component(M1_1, "api/openapi", "TypeScript", "1 fichiers")
}
Boundary(L2, "Services applicatifs", "layer") {
Component(M2_0, "app", "React, .css", "3 fichiers")
Component(M2_1, "api-docs", "React", "1 fichiers")
}
Boundary(L3, "Données et infrastructure", "layer") {
Component(M3_0, "kroki", "TypeScript", "4 fichiers")
}
Boundary(L4, "Source principale", "layer") {
Component(M4_0, "(root)", "TypeScript, .mjs", "5 fichiers")
}
Boundary(L5, "Tests", "layer") {
Component(M5_0, "kroki", "TypeScript", "4 fichiers")
Component(M5_1, "api", "TypeScript", "1 fichiers")
}
Boundary(L6, "Build, CI et hébergement", "layer") {
Component(M6_0, ".github", ".yml, .md", "4 fichiers")
Component(M6_1, "(root)", ".json", "1 fichiers")
Component(M6_2, ".devcontainer", ".json", "1 fichiers")
}
}
@enduml
UML 4 · Code
4 · Code

Déclarations, champs et méthodes sélectionnés, regroupés par fichier source. Aucun héritage ni appel n’est déduit. Rendu avec uml-mcp.

Source PlantUML
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
top to bottom direction
hide empty members
package "kroki-playground" {
object "app/api/generate-diagram/route.ts" as FN0 {
  getKrokiBaseUrl()
  mimeTypeForFormat()
  parseBody()
}
object "lib/kroki/encode.ts" as FN1 {
  textEncode()
  bytesToBase64Url()
  binaryToBase64()
  as()
}
}
@enduml

8.3. Logique métier

Aucune classe n’a été extraite. Voici les plus gros fichiers source et leurs fonctions.

app/api/generate-diagram/route.ts
getKrokiBaseUrl, mimeTypeForFormat, parseBody
lib/kroki/validate.ts
Aucune fonction nommée.
lib/kroki/diagramTypes.ts
Aucune fonction nommée.
app/api-docs/page.tsx
Aucune fonction nommée.
lib/kroki/encode.ts
textEncode, bytesToBase64Url, binaryToBase64, as
app/page.tsx
Aucune fonction nommée.

8.4. Base de données et persistance

8.5. Intégrations externes

Clients HTTP

fetch

Hôtes nommés dans le code

8.6. Stack et dépendances

Node.js package.json 5 à l’exécution, 13 dev

node >=20.9.0

Ouvrir le manifeste

Dépendances externes

18 paquets déclarés (5 à l’exécution, 13 pour le développement) dans package.json.

Tableau des paquets 18
Dépendances externes
PaquetVersionUsageRôleRegistre
next^16.0.0exécutionInterface utilisateurnpmjs.com
pako^2.1.0exécutionzlib port to javascript - fast, modularized, with browser supportnpmjs.com
react^19.0.0exécutionInterface utilisateurnpmjs.com
react-dom^19.0.0exécutionInterface utilisateurnpmjs.com
swagger-ui-react^5.18.2exécution—npmjs.com
@tailwindcss/postcss^4.1.0développementInterface utilisateurnpmjs.com
@types/node^22.10.0développementTypagenpmjs.com
@types/pako^2.0.3développementTypagenpmjs.com
@types/react^19.0.0développementTypagenpmjs.com
@types/react-dom^19.0.0développementTypagenpmjs.com
@types/swagger-ui-react^5.18.0développementTypagenpmjs.com
eslint^9.0.0développementAnalyse et formatagenpmjs.com
eslint-config-next^16.0.0développementAnalyse et formatagenpmjs.com
postcss^8.4.49développementOutils de buildnpmjs.com
tailwindcss^4.1.0développementInterface utilisateurnpmjs.com
typescript^5.7.0développementTypagenpmjs.com
vite-tsconfig-paths^6.1.1développementOutils de buildnpmjs.com
vitest^3.0.0développementTestsnpmjs.com

8.7. Pipeline CI/CD

Aucun pipeline CI/CD dans le dépôt. Le code se construit et se lance à la main, comme décrit plus haut.

8.8. Déploiement

Mermaid Schéma de déploiement
flowchart LR
  repo[("Dépôt GitHub")]
  host_Vercel("Vercel<br/>vercel.json")
  repo -.->|"configuré"| host_Vercel
UML Déploiement
Déploiement

Le nœud extérieur est l’endroit où le code s’exécute. Chaque image de base pointe vers ce qu’elle construit, les flèches pleines mènent aux bases de données et les pointillées aux services externes. Rendu avec uml-mcp.

Source PlantUML
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
cloud "Vercel" as H {
  artifact "kroki-playground" as APP
}
cloud "Kroki" as E0
APP ..> E0
@enduml

Où il s’exécute

8.9. Sécurité

Chaîne d’approvisionnement

Variables d’environnement 2

La page reprend les noms sans leurs valeurs et souligne ceux qui ressemblent à des secrets.

KROKI_BASE_URL NEXT_PUBLIC_KROKI_BASE_URL

8.10. Tests automatisés

Fichiers de test
5
Fichiers source
16
Cas de test, environ
26
Tests unitaires
5

Aucun rapport chiffré de couverture dans les sources analysées.

Où sont les tests

lib/kroki 4 app/api/generate-diagram 1

Rien trouvé pour: Interface publique, Interface privée, Services, Entités, Supervision.

9. API HTTP de diagrammes

Le fichier de route définit GET et POST /api/generate-diagram. POST lit du JSON; GET lit les mêmes champs dans les paramètres de requête. Le gestionnaire valide le type et le format, compresse la source UTF-8 avec DEFLATE, l’encode pour une URL et appelle le moteur Kroki choisi.

Exemple de requête
POST /api/generate-diagram
Content-Type: application/json

{
  "selectedDiagram": "mermaid",
  "diagramSource": "flowchart LR\n  Client --> Server",
  "outputFormat": "svg"
}

9.1. Réponse et erreurs

Une réponse JSON réussie contient diagramUrl, diagramData (octets en base64) et mimeType. Décodez diagramData avec mimeType pour afficher le résultat. La réponse n’est pas un SVG brut.
HTTP 400 couvre MISSING_DIAGRAM_TYPE, INVALID_DIAGRAM_TYPE, SOURCE_TOO_LARGE et INVALID_OUTPUT_FORMAT. Une erreur HTTP de Kroki devient 502 KROKI_UPSTREAM_ERROR avec upstreamStatus; une exception devient 500 INTERNAL_ERROR. Pour une 502, inspectez le format choisi et la réponse Kroki avant de réessayer. Testez un petit graphe sur un déploiement local.
Authentification, limites et pagination

La route inspectée ne contient ni authentification, ni pagination, ni limiteur de débit. Un proxy de déploiement peut imposer ses propres règles. La source est limitée à 512 000 caractères. KROKI_BASE_URL configure les requêtes serveur; NEXT_PUBLIC_KROKI_BASE_URL configure les aperçus du navigateur. Le README mentionne /api/generateDiagram, tandis que ce fichier définit la route avec trait d’union.

10. Référence

21 / 21 fichiers admissibles lus (38 dans l’arbre); 0 trop volumineux, 0 échec de lecture et 0 diagnostic de syntaxe.

Ce que couvre l’analyse

Les dossiers connus de dépendances et de compilation, les fichiers d’identifiants et les binaires sont exclus. La collecte couvre les README, les manifestes reconnus et les fichiers source pris en charge.

Les statistiques Linguist couvrent l’ensemble du dépôt et peuvent inclure d’autres langages.

12. Fichiers à lire 4

13. Glossaire

Dépôt

Les fichiers source, la configuration et l’historique versionné d’un projet.

README

Le document d’entrée du dépôt, qui présente généralement son rôle et son installation.

Dépendance

Une bibliothèque, un outil ou un service nécessaire à la compilation ou à l’exécution d’un composant.

API

Une interface par laquelle des composants logiciels échangent des requêtes et des résultats. Une API n’utilise pas nécessairement HTTP.

HTTP

Un protocole de requête et réponse utilisé par les navigateurs et services web. Une requête comprend une méthode, un chemin, des en-têtes et parfois un corps.

Interface en ligne de commande

Une interface textuelle où les commandes et arguments choisissent les opérations. Les codes de retour permettent aux scripts de détecter un succès ou un échec.

Compilation

Les étapes qui transforment les sources et dépendances en programme exécutable ou en livrable distribuable.

Mermaid

Un langage de diagrammes textuel. Les nœuds et liens décrivent un modèle ; le diagramme n’exécute pas le projet.

GPU

Un processeur conçu pour les calculs parallèles, dont le rendu graphique et de nombreuses opérations numériques.

Fork

Un dépôt distinct dérivé d’un autre projet. Une modification du fork ne devient pas automatiquement une modification du projet amont.

14. Références

  1. antoinebou12. (2026, 5 novembre). kroki-playground. [Software repository] github.com.
  2. antoinebou12. (2026, 5 novembre). kroki-playground: README. [Repository documentation] github.com.
  3. antoinebou12. (2026, 5 novembre). app/api/generate-diagram/route.ts. [Source file] github.com.
  4. antoinebou12. (2026, 5 novembre). lib/kroki/encode.ts. [Source file] github.com.
  5. antoinebou12. (2026, 5 novembre). lib/kroki/validate.ts. [Source file] github.com.
  6. antoinebou12. (2026, 5 novembre). package.json. [Source file] github.com.
  7. Boucher, A. (2026, 23 octobre). kroki-playground : Un éditeur, une API et un moteur de rendu. [Project article] antoineboucher.info.

Les sources sans date de publication indiquent la date de leur dernière vérification, le 5 novembre 2026. Les liens des fichiers conservent la révision inspectée lorsqu’elle est disponible.