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 du dépôtTypeScript 98.19%3
Parts calculées à partir des octets GitHub Linguist.
| Langage | % | Octets |
|---|---|---|
| TypeScript | 33 686 | |
| JavaScript | 340 | |
| CSS | 282 |
Aperçu
Pourquoi il existe
Suite d'expérimentation de diagrammes en TypeScript déployée sur Vercel avec rendu instantané.
Cas d’usage
Prototypage rapide de diagrammes d'architecture variés.
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
package.json
devnext devbuildnext buildstartnext startlinteslint .testvitest run
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
Requirements
README.md
- Node.js ≥ 22 (see .nvmrc and engines in package.json). Match your Vercel project Node version to your environment.
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
Environment variables
README.md
| Variable | Where | Description |
|---|
Environment variables
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
Deployment (Vercel)
README.md
Développement et contributions
Contributing
README.md
Contributing
CONTRIBUTING.md
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.
Architecture
Les composants et leurs liens restent lisibles en texte. Le diagramme ajoute une vue interactive.
- Éditeur de texte
- Route API Next.js
- Valider et encoder
- Service Kroki configuré
- Résultat base64 et aperçu
Liens vérifiés dans le dépôt.
Mermaid Diagramme interactif (chargement à l’ouverture)
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.
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"
}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.
Structure des fichiers
La carte montre les fichiers inspectés et leur organisation.
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.
Carte des fichiers
flowchart TD
root["kroki-playground"]
f0["package.json"]
root --> f0
f1["lib/kroki/encode.ts"]
root --> f1
f2["lib/kroki/validate.ts"]
root --> f2
f3["app/api/generate-diagram/route.ts"]
root --> f3
f4["README.md"]
root --> f4
f5["eslint.config.mjs"]
root --> f5
f6["next.config.ts"]
root --> f6
f7["postcss.config.mjs"]
root --> f7
f8["vitest.config.ts"]
root --> f8
f9["app/layout.tsx"]
root --> f9
f10["app/page.tsx"]
root --> f10
f11["components/DiagramGenerator.tsx"]
root --> f11
f12["app/api-docs/page.tsx"]
root --> f12
f13["lib/kroki/diagramLabels.test.ts"]
root --> f13
f14["lib/kroki/diagramLabels.ts"]
root --> f14
f15["lib/kroki/diagramTypes.test.ts"]
root --> f15