puml2c4

0.2.0 verified Fri May 01 auth: no javascript

puml2c4 is a PlantUML C4 to LikeC4 transpiler (v0.2.0, early stage, pre-1.0). It converts existing PlantUML C4 diagrams into the LikeC4 DSL format, enabling interactive visualizations with drill-down and auto-layout. Supports persons, systems, containers, components, boundaries, deployment nodes, and relationships with standard PlantUML C4 syntax. Unlike manual conversion, puml2c4 automates the migration of PlantUML-based architecture diagrams to LikeC4 without rewriting. Currently supports Node.js >=18 and is distributed as an npm package with TypeScript type declarations. Release cadence is irregular; users should expect breaking changes until 1.0.

Common errors

error Error: ENOENT: no such file or directory, open '<path>/<file>.c4' ↓

cause Output directory does not exist.

fix

Create the output directory before running: mkdir -p out/

error Error: Unexpected token '}' ... ↓

cause Input file contains unsupported PlantUML C4 syntax or syntax error.

fix

Simplify the diagram to only supported elements (see README). Remove unsupported macros like Lay_D.

error Error: Cannot find module 'puml2c4' ↓

cause Using import/require instead of CLI npx or global install.

fix

Use npx puml2c4 or npm install -g puml2c4 then puml2c4.

Warnings

deprecated v0.2.0 is pre-1.0; breaking changes may occur without major version bump. ↓

fix Pin version in CI scripts: 'npx puml2c4@0.2.0'

gotcha Output directory must exist; tool does not create intermediate directories automatically. ↓

fix Use 'mkdir -p <dir>' before running convert.

gotcha Some PlantUML C4 features like 'Lay_D' or 'Layout_LeftRight' are not supported. ↓

fix Manually adjust layout in LikeC4 after conversion.

gotcha Tool is meant for CLI use; there is no JavaScript API exported. ↓

fix Use child_process.exec() if integration needed, but not officially supported.

Install

npm install puml2c4

yarn add puml2c4

pnpm add puml2c4

Imports

puml2c4
wrong
```
import puml2c4 from 'puml2c4'
```
correct
```
npx puml2c4 convert <input> -o <output>
```
puml2c4 is a CLI tool, not a library. Use via npx or global install.

Quickstart

Converts a directory of PlantUML C4 files to LikeC4 format using npx.

mkdir -p diagrams out
cat > diagrams/sample.puml << 'EOF'
@startuml
!include C4_Context.puml
Person(user, "User", "A customer")
System(app, "Application", "Main system")
System_Ext(email, "Email Service")
Rel(user, app, "Uses", "HTTPS")
Rel(app, email, "Sends notifications", "SMTP")
@enduml
EOF
npx -y puml2c4@0.2.0 convert diagrams/ -o out/context.c4