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.
- Langages
- 3Répartition du code
- 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.
| Langage | % | Octets |
|---|---|---|
| TypeScript | 33 686 | |
| JavaScript | 340 | |
| CSS | 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.
- 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
- Lancer npm install puis npm run dev et ouvrir http://localhost:3000.
- Choisir plantuml dans la liste des types et coller la source @startuml … @enduml.
- L’aperçu SVG se met à jour depuis Kroki à mesure que la source change.
- Copier l’URL de la page, qui porte maintenant ?type=plantuml&source=<encodé>, et l’envoyer.
- 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.
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
devnext devbuildnext buildstartnext startlinteslint .testvitest 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.
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).
Configuration et utilisation
5.3. Environment variables
README.md
| Variable | Where | Description |
|---|
5.4. Environment variables (CONTRIBUTING.md)
CONTRIBUTING.md
| Variable | Where | Description |
|---|---|---|
| Create a .env file locally when you need non-default Kroki URLs or other local-only settings. Never commit secrets; .env is gitignored. |
Exploitation et dépannage
5.5. Deployment (Vercel)
README.md
Développement et contributions
5.6. Contributing
README.md
5.7. Contributing (CONTRIBUTING.md)
CONTRIBUTING.md
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.
Éditeur de texte
- Vers Route API Next.js
- Depuis Résultat base64 et aperçu
Route API Next.js
- Depuis Éditeur de texte
- Vers Valider et encoder
Valider et encoder
- Depuis Route API Next.js
- Vers Service Kroki configuré
Service Kroki configuré
- Depuis Valider et encoder
- Vers Résultat base64 et aperçu
Résultat base64 et aperçu
- Depuis Service Kroki configuré
- Vers Éditeur de texte
Mermaid Diagramme interactif
Vue générale des composants et des échanges vérifiés dans le dépôt.

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
| Module | Couche | Fichiers | Types | Extensions |
|---|---|---|---|---|
(root) | Source principale | 5 | 0 | .ts .mjs |
kroki | Données et infrastructure | 4 | 0 | .ts |
app | Services applicatifs | 3 | 0 | .tsx .css |
api-docs | Services applicatifs | 1 | 0 | .tsx |
api/generate-diagram | Points d’entrée et API | 1 | 0 | .ts |
api/openapi | Points d’entrée et API | 1 | 0 | .ts |
components | Présentation | 1 | 0 | .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
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
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
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
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.tsgetKrokiBaseUrl, mimeTypeForFormat, parseBodylib/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.tstextEncode, bytesToBase64Url, binaryToBase64, asapp/page.tsx- Aucune fonction nommée.
8.4. Base de données et persistance
8.5. Intégrations externes
Clients HTTP
Hôtes nommés dans le code
kroki.io2 fichiersapp/api/generate-diagram/route.ts:5
8.6. Stack et dépendances
Dépendances externes
18 paquets déclarés (5 à l’exécution, 13 pour le développement) dans package.json.
Tableau des paquets 18
| Paquet | Version | Usage | Rôle | Registre |
|---|---|---|---|---|
next | ^16.0.0 | exécution | Interface utilisateur | npmjs.com |
pako | ^2.1.0 | exécution | zlib port to javascript - fast, modularized, with browser support | npmjs.com |
react | ^19.0.0 | exécution | Interface utilisateur | npmjs.com |
react-dom | ^19.0.0 | exécution | Interface utilisateur | npmjs.com |
swagger-ui-react | ^5.18.2 | exécution | — | npmjs.com |
@tailwindcss/postcss | ^4.1.0 | développement | Interface utilisateur | npmjs.com |
@types/node | ^22.10.0 | développement | Typage | npmjs.com |
@types/pako | ^2.0.3 | développement | Typage | npmjs.com |
@types/react | ^19.0.0 | développement | Typage | npmjs.com |
@types/react-dom | ^19.0.0 | développement | Typage | npmjs.com |
@types/swagger-ui-react | ^5.18.0 | développement | Typage | npmjs.com |
eslint | ^9.0.0 | développement | Analyse et formatage | npmjs.com |
eslint-config-next | ^16.0.0 | développement | Analyse et formatage | npmjs.com |
postcss | ^8.4.49 | développement | Outils de build | npmjs.com |
tailwindcss | ^4.1.0 | développement | Interface utilisateur | npmjs.com |
typescript | ^5.7.0 | développement | Typage | npmjs.com |
vite-tsconfig-paths | ^6.1.1 | développement | Outils de build | npmjs.com |
vitest | ^3.0.0 | développement | Tests | npmjs.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
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.
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
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.
POST /api/generate-diagram
Content-Type: application/json
{
"selectedDiagram": "mermaid",
"diagramSource": "flowchart LR\n Client --> Server",
"outputFormat": "svg"
}9.1. Réponse et erreurs
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
- antoinebou12. (2026, 5 novembre). kroki-playground. [Software repository] github.com.
- antoinebou12. (2026, 5 novembre). kroki-playground: README. [Repository documentation] github.com.
- antoinebou12. (2026, 5 novembre). app/api/generate-diagram/route.ts. [Source file] github.com.
- antoinebou12. (2026, 5 novembre). lib/kroki/encode.ts. [Source file] github.com.
- antoinebou12. (2026, 5 novembre). lib/kroki/validate.ts. [Source file] github.com.
- antoinebou12. (2026, 5 novembre). package.json. [Source file] github.com.
- 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.