Table of contents

kroki-playground: An editor, an API and a renderer

kroki-playground is a Next.js interface for editing text diagrams and previewing their output. Its server route validates the requested diagram type and format, encodes the source and fetches the rendered result from Kroki.

Application and services API

Updated 2026-10-23
TypeScript · 98.19%
MIT

Node.js Vitest

View source README Open playground Markdown

Languages: 3Code breakdown
Documented components: 2Explore modules
Source documents: 2Read the instructions

Repository languagesTypeScript 98.19%3

Shares calculated from GitHub Linguist bytes.

TypeScript98.19%

98.19%33,686 bytes

JavaScript0.99%

0.99%340 bytes

CSS0.82%

0.82%282 bytes

Language	%	Bytes
TypeScript	98.19%	33,686
JavaScript	0.99%	340
CSS	0.82%	282

GitHub README Language statistics

1. Overview

1.1. Why it exists

Serverless diagram experimentation suite in TypeScript running on Vercel with instant preview.

1.2. Best fit

Rapid prototyping of PlantUML, Mermaid, GraphViz, and C4 architecture diagrams.

2. Use cases

A Next.js playground to write diagram source for Kroki, preview the SVG live and share it through the URL.

People on the left, external systems on the right; each oval is a use case backed by the files cited below.

Preview a diagram live: Diagram authorKroki server
DiagramGenerator.tsx deflates the source with encodeDiagramPayload() (pako, base64url) and loads <base>/<type>/svg/<encoded> from kroki.io or NEXT_PUBLIC_KROKI_BASE_URL.
Switch between diagram types: Diagram author
lib/kroki/diagramTypes.ts lists the Kroki route names (plantuml, mermaid, graphviz, d2, vega-lite…) offered in the type picker.
Share or download the result: Diagram author
The page pushes ?type=…&source=… into the browser history, can copy the Kroki URL to the clipboard and saves the image as diagram.svg.
Render through the REST API: API client developerKroki server
app/api/generate-diagram/route.ts accepts GET or POST with diagramSource, selectedDiagram and outputFormat and returns base64 diagramData; the README and openapi.yaml name the path /api/generateDiagram.
Read the OpenAPI docs: API client developer
/api-docs renders public/openapi.yaml with swagger-ui-react, and GET /api/openapi serves the specification.

2.1. Scenario: Sketching a sequence diagram and sending it to a teammate

Run npm install then npm run dev and open http://localhost:3000.
Choose plantuml in the type list and paste the @startuml … @enduml source.
The SVG preview refreshes from Kroki as the source changes.
Copy the page URL, which now carries ?type=plantuml&source=<encoded>, and send it.
Click download to save diagram.svg for the design document.

Files readREADME.mdpackage.jsoncomponents/DiagramGenerator.tsxlib/kroki/encode.tslib/kroki/diagramTypes.tsapp/api/generate-diagram/route.tsapp/api-docs/page.tsxpublic/openapi.yaml

3. Try it

Address published in the repository README. The page opens in a sandboxed frame, only when you ask.

Open in a new tab https://kroki-playground.vercel.app/

4. Getting started

These commands come from the repository documentation. They were not run during this review.

Tasks declared in manifests

4.1. `package.json`

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

5. Repository references

Excerpts from the repository’s guides, in their original language. Links open the inspected source revision.

Prerequisites and first run

5.1. Requirements

README.md

Node.js ≥ 22 (see .nvmrc and engines in package.json). Match your Vercel project Node version to your environment.

Read the full instructions ↗

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).

Read the full instructions ↗

Configuration and usage

5.3. Environment variables

README.md

Variable	Where	Description

Read the full instructions ↗

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.

Read the full instructions ↗

Operations and troubleshooting

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.

Read the full instructions ↗

Development and contributions

5.6. Contributing

README.md

See CONTRIBUTING.md. Report security vulnerabilities per SECURITY.md.

Read the full instructions ↗

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.

Read the full instructions ↗

Source documentation

2 documents read from 2 candidates.

6. Features and components 2

Validation before rendering: app/api/generate-diagram/route.ts accepts GET and POST inputs through a shared validator. encodeDiagramPayload prepares the source for the Kroki URL. KROKI_BASE_URL selects the server-side rendering endpoint.
Response and failure states: The route reads the returned bytes and responds with diagramUrl, base64 diagramData and mimeType. A non-success response from Kroki becomes a 502 with an upstream error code, distinct from invalid input.

7. Architecture

Expand a component to follow its connections, or explore the full diagram.

System components Context

Text editor
- To Next.js API route
- From Base64 result and preview
Next.js API route
- From Text editor
- To Validate and encode
Validate and encode
- From Next.js API route
- To Configured Kroki service
Configured Kroki service
- From Validate and encode
- To Base64 result and preview
Base64 result and preview
- From Configured Kroki service
- To Text editor

Mermaid Interactive diagram

System overview of the components and connections verified in the repository.

Static architecture view for kroki-playground — Static preview. The interactive diagram replaces it after Mermaid loads.

flowchart LR
  n0["Text editor"]
  n1["Next.js API route"]
  n2["Validate and encode"]
  n3["Configured Kroki service"]
  n4["Base64 result and preview"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 --> n0

Text version of the diagram

Text editor → Next.js API route
Next.js API route → Validate and encode
Validate and encode → Configured Kroki service
Configured Kroki service → Base64 result and preview
Base64 result and preview → Text editor

Follow one path through the code

Follow POST from req.json to validation and the upstream fetch. The response contains encoded image bytes, not raw SVG as the entire HTTP body. A consumer must use the returned MIME type when displaying those bytes.

8. Technical dossier

Built from the source at commit 8def712 (24 files). Each item comes from a pattern match in the code, so open the linked file before relying on it.

8.1. Layers and modules

Folders are sorted into layers by name, from the user interface down to data access. Because the sorting uses names only, the diagram says nothing about calls between layers.

Mermaid Layered view

flowchart TB
  subgraph L_presentation["Presentation"]
    direction TB
    presentation_0["components<br/>1 file"]
  end
  subgraph L_interface["Entry points and API"]
    direction TB
    interface_0["api/generate-diagram<br/>1 file"]
    interface_1["api/openapi<br/>1 file"]
  end
  subgraph L_application["Application services"]
    direction TB
    application_0["app<br/>3 files"]
    application_1["api-docs<br/>1 file"]
  end
  subgraph L_infrastructure["Data and infrastructure"]
    direction TB
    infrastructure_0["kroki<br/>4 files"]
  end
  subgraph L_core["Core source"]
    direction TB
    core_0["(root)<br/>5 files"]
  end
  subgraph L_tests["Tests"]
    direction TB
    tests_0["kroki<br/>4 files"]
    tests_1["api<br/>1 file"]
  end
  subgraph L_hosting["Build, CI and hosting"]
    direction TB
    hosting_0[".github<br/>4 files"]
    hosting_1["(root)<br/>1 file"]
    hosting_2[".devcontainer<br/>1 file"]
  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 and their main layer
Module	Layer	Files	Extensions
`(root)`	Core source	5	.ts .mjs
`kroki`	Data and infrastructure	4	.ts
`app`	Application services	3	.tsx .css
`api-docs`	Application services	1	.tsx
`api/generate-diagram`	Entry points and API	1	.ts
`api/openapi`	Entry points and API	1	.ts
`components`	Presentation	1	.tsx

8.2. C4 model

From system context to code declarations. Each level reflects the available source evidence.

UML 1 · System context

The widest C4 view: who uses the project and which outside systems and data stores it relies on. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
System(SYS, "kroki-playground", "kroki-playground is a Next.js interface for editing text diagrams and…")
System_Ext(E0, "Kroki")
Rel(SYS, E0, "Calls")
@enduml

UML 2 · Containers

One level closer: the parts that run separately inside the project, their main language and how calls flow between them. Rendered with uml-mcp.

PlantUML source

@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, "Calls")
@enduml

UML 3 · Components and layers

Modules grouped by source-layer classification. Boundaries show organization, not runtime isolation or call relationships. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "kroki-playground") {
Boundary(L0, "Presentation", "layer") {
Component(M0_0, "components", "React", "1 files")
}
Boundary(L1, "Entry points and API", "layer") {
Component(M1_0, "api/generate-diagram", "TypeScript", "1 files")
Component(M1_1, "api/openapi", "TypeScript", "1 files")
}
Boundary(L2, "Application services", "layer") {
Component(M2_0, "app", "React, .css", "3 files")
Component(M2_1, "api-docs", "React", "1 files")
}
Boundary(L3, "Data and infrastructure", "layer") {
Component(M3_0, "kroki", "TypeScript", "4 files")
}
Boundary(L4, "Core source", "layer") {
Component(M4_0, "(root)", "TypeScript, .mjs", "5 files")
}
Boundary(L5, "Tests", "layer") {
Component(M5_0, "kroki", "TypeScript", "4 files")
Component(M5_1, "api", "TypeScript", "1 files")
}
Boundary(L6, "Build, CI and hosting", "layer") {
Component(M6_0, ".github", ".yml, .md", "4 files")
Component(M6_1, "(root)", ".json", "1 files")
Component(M6_2, ".devcontainer", ".json", "1 files")
}
}
@enduml

UML 4 · Code

Selected declarations, fields and methods grouped by source file. No inheritance or call edges are inferred. Rendered with uml-mcp.

PlantUML source

@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. Business logic

No classes were extracted, so these are the largest source files and their functions.

app/api/generate-diagram/route.ts: getKrokiBaseUrl, mimeTypeForFormat, parseBody
lib/kroki/validate.ts: No named functions.
lib/kroki/diagramTypes.ts: No named functions.
app/api-docs/page.tsx: No named functions.
lib/kroki/encode.ts: textEncode, bytesToBase64Url, binaryToBase64, as
app/page.tsx: No named functions.

8.6. Stack and dependencies

Node.js package.json 5 runtime, 13 dev

node >=20.9.0

Open the manifest

External dependencies

18 declared packages (5 runtime, 13 development) in package.json.

Package table 18

External dependencies
Package	Version	Scope	Purpose	Registry
`next`	`^16.0.0`	runtime	User interface	npmjs.com
`pako`	`^2.1.0`	runtime	zlib port to javascript - fast, modularized, with browser support	npmjs.com
`react`	`^19.0.0`	runtime	User interface	npmjs.com
`react-dom`	`^19.0.0`	runtime	User interface	npmjs.com
`swagger-ui-react`	`^5.18.2`	runtime	—	npmjs.com
`@tailwindcss/postcss`	`^4.1.0`	development	User interface	npmjs.com
`@types/node`	`^22.10.0`	development	Type checking	npmjs.com
`@types/pako`	`^2.0.3`	development	Type checking	npmjs.com
`@types/react`	`^19.0.0`	development	Type checking	npmjs.com
`@types/react-dom`	`^19.0.0`	development	Type checking	npmjs.com
`@types/swagger-ui-react`	`^5.18.0`	development	Type checking	npmjs.com
`eslint`	`^9.0.0`	development	Linting and formatting	npmjs.com
`eslint-config-next`	`^16.0.0`	development	Linting and formatting	npmjs.com
`postcss`	`^8.4.49`	development	Build tooling	npmjs.com
`tailwindcss`	`^4.1.0`	development	User interface	npmjs.com
`typescript`	`^5.7.0`	development	Type checking	npmjs.com
`vite-tsconfig-paths`	`^6.1.1`	development	Build tooling	npmjs.com
`vitest`	`^3.0.0`	development	Testing	npmjs.com

8.7. CI/CD pipeline

No CI/CD pipeline in the repository. The code is built and run by hand, as described above.

8.8. Deployment

Mermaid Deployment diagram

flowchart LR
  repo[("GitHub repository")]
  host_Vercel("Vercel<br/>vercel.json")
  repo -.->|"configured"| host_Vercel

UML Deployment

The outer node is where the code runs. Each base image points to what it builds, solid arrows lead to databases and dashed ones to outside services. Rendered with uml-mcp.

PlantUML source

@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

Where it runs

8.9. Security

Supply chain

Environment variables 2

The page lists names without their values and underlines the ones that look like secrets.

KROKI_BASE_URL NEXT_PUBLIC_KROKI_BASE_URL

8.10. Testing

Test files: 5
Source files: 16
Test cases, about: 26
Unit tests: 5

Vitest

No measured coverage report in the analyzed sources.

Where the tests are

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

Nothing found for: Public interface, Private interface, Services, Entities, Monitoring.

9. Diagram HTTP API

The route file defines GET and POST /api/generate-diagram. POST reads JSON; GET reads the same fields from query parameters. The handler validates the diagram type and format, compresses UTF-8 source with DEFLATE, encodes it for a URL and fetches the selected Kroki renderer.

Request example

POST /api/generate-diagram
Content-Type: application/json

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

9.1. Response and errors

A successful JSON response contains diagramUrl, diagramData (base64 bytes) and mimeType. Decode diagramData using mimeType when displaying the result. This is not a raw SVG response.

HTTP 400 covers MISSING_DIAGRAM_TYPE, INVALID_DIAGRAM_TYPE, SOURCE_TOO_LARGE and INVALID_OUTPUT_FORMAT. A Kroki HTTP failure becomes 502 KROKI_UPSTREAM_ERROR with upstreamStatus; a thrown request or decoding error becomes 500 INTERNAL_ERROR. For a 502, inspect the selected format and Kroki response before retrying. Test with a small graph against a local deployment.

Authentication, limits and pagination

The inspected route has no authentication, pagination or rate limiter. A deployment proxy may impose its own rules. The source limit is 512,000 characters. KROKI_BASE_URL configures server requests; NEXT_PUBLIC_KROKI_BASE_URL configures browser previews. The README mentions /api/generateDiagram, while this source file defines the hyphenated route.

10. Reference

21 / 21 eligible files read (38 in the tree); 0 oversized, 0 failed reads and 0 syntax diagnostics.

What the scan covers

Known dependency/build folders, credential files and binaries are excluded. The scan covers READMEs, recognized manifests and parser-supported source files.

Linguist statistics cover the whole repository and may include other languages.

12. Files to read 4

13. Glossary

Repository

The versioned source files, configuration, and history of a project.

README

The repository’s entry document, usually covering its purpose and initial setup.

Dependency

A library, tool, or service that another component needs to build or run.

API

An interface through which software components exchange requests and results. An API does not have to use HTTP.

HTTP

A request-and-response protocol used by browsers and web services. A method, path, headers, and optional body describe a request.

CLI

A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.

Build

The steps that turn source files and dependencies into a runnable program or distributable artifact.

Mermaid

A text-based diagram language. Nodes and connections describe a model; the diagram itself does not execute the project.

GPU

A processor designed for parallel workloads, including graphics rendering and many numerical operations.

Fork

A separate repository derived from another project. A change in a fork is not automatically a change in the upstream project.

14. References

antoinebou12. (2026, November 5). kroki-playground. [Software repository] github.com.
antoinebou12. (2026, November 5). kroki-playground: README. [Repository documentation] github.com.
antoinebou12. (2026, November 5). app/api/generate-diagram/route.ts. [Source file] github.com.
antoinebou12. (2026, November 5). lib/kroki/encode.ts. [Source file] github.com.
antoinebou12. (2026, November 5). lib/kroki/validate.ts. [Source file] github.com.
antoinebou12. (2026, November 5). package.json. [Source file] github.com.
Boucher, A. (2026, October 23). kroki-playground: An editor, an API and a renderer. [Project article] antoineboucher.info.

Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.

1. Overview

1.1. Why it exists

1.2. Best fit

2. Use cases

2.1. Scenario: Sketching a sequence diagram and sending it to a teammate

3. Try it

4. Getting started

4.1. package.json

5. Repository references

5.1. Requirements

5.2. Prerequisites

5.3. Environment variables

5.4. Environment variables (CONTRIBUTING.md)

5.5. Deployment (Vercel)

5.6. Contributing

5.7. Contributing (CONTRIBUTING.md)

6. Features and components 2

7. Architecture

8. Technical dossier

8.1. Layers and modules

8.2. C4 model

8.3. Business logic

8.4. Database and persistence

8.5. External integrations

HTTP clients

Hosts named in the code

8.6. Stack and dependencies

External dependencies

8.7. CI/CD pipeline

8.8. Deployment

Where it runs

8.9. Security

Supply chain

Environment variables 2

8.10. Testing

Where the tests are

9. Diagram HTTP API

9.1. Response and errors

10. Reference

12. Files to read 4

13. Glossary

14. References

4.1. `package.json`