likec4 v1.26.1

LikeC4

likec4 is a CLI tool for various operations and automation over LikeC4 projects.

Features:

• Preview diagrams in a local web server (with lightning-fast updates) ⚡️
• Build a static .website (deploy to github pages, netlify...) 🔗
• Export to PNG, JSON, Mermaid, Dot, D2 (if you need something static) 🖼️
• Generate React components (for custom integrations ) 🛠️

Install

Compatibility Note:\ LikeC4 requires Node.js version 20+

Local installation

If you're using it in an npm project, install it as a development dependency:

npm install --save-dev likec4

You can reference it directly in the package.json#scripts object:

{
  scripts: {
    dev: 'likec4 serve ...',
    build: 'likec4 build ...'
  }
}

Global installation

To use the CLI globally, you can call it with npx:

npx likec4 [command]

If you want to use it in any arbitrary project without npx, install it globally:

npm install --global likec4

# Then, you can call `likec4` directly:
likec4 [command]

Usage

Refer to the help:

likec4 build -h
likec4 codegen react -h

Almost all commands have a --help option and provide usage examples.

Preview diagrams

In a folder with LikeC4 sources:

likec4 serve

# Aliases:
likec4 start
likec4 dev

This recursively searches for *.c4, *.likec4 files in the current folder, parses and serves diagrams in a local web server.\ Any changes in the sources trigger a super-fast hot update and you see changes in the browser immediately.

Tip:\ You can use likec4 start [path] in a separate terminal window and keep it running while you're editing diagrams in editor, or even serve multiple projects at once.

Build static website

Build a single HTML with diagrams, ready to be embedded into your website:

likec4 build -o ./dist

Example https://template.likec4.dev

When you deploy the website, you can use the "Share" button to get links.

Tip:\ likec4/template repository demonstrates how to deploy to github pages.

There is also a supplementary command to preview the build:

likec4 preview -o ./dist

For example, this command can be used on CI, to compare diagrams with ones from the previous/main build.

Tip:\ The website root is strictly bound to the given base path (/ by default). If you need a relocatable bundle you may use --base "./".

Export to PNG

likec4 export png -o ./assets

This command starts the local web server and uses Playwright to take screenshots.\ If you plan to use it on CI, refer to Playwright documentation for details.

Export to JSON

likec4 export json -o dump.json

Export to Mermaid, Dot, D2

Export to various formats via codegen:

likec4 codegen mmd
likec4 codegen mermaid
likec4 codegen dot
likec4 codegen d2

Generate React components

likec4 codegen react --outfile ./src/likec4.generated.tsx

Check documentation

Output file should have .tsx extension\ By default, it generates likec4.generated.tsx in current directory

Generate structured data

Generate a TypeScript file with LikeC4Views object, which contains all diagrams and their metadata.

likec4 codegen views-data --outfile ./src/likec4.generated.ts

#Aliases
likec4 codegen views ...
likec4 codegen ts ...

Output file should have .ts extension\ By default, it generates likec4.generated.ts in current directory

API Usage

You can access and traverse your architecture model programmatically using the LikeC4 Model API.

From workspace

Recursively searches and parses source files from the wokrkspace directory:

import { LikeC4 } from 'likec4'

const likec4 = await LikeC4.fromWorkspace('path to workspace', opts)

From source

Parses the model from the string:

import { LikeC4 } from "likec4"

const likec4 = await LikeC4.fromSource(`
  specification {
    element system
    element user
  }
  model {
    customer = user 'Customer'
    cloud = system 'System'
  }
  views {
    view index {
      include *
    }
  }
`, opts)

Example

When the model is initialized, you can use the following methods to query and traverse it.

import { LikeC4 } from "likec4"

const likec4 = await LikeC4.fromSource(`....`)

// Validation errors
console.log(likec4.getErrors())

// Traverse the model
const model = likec4.model()
model
  .element('cloud.backend.api')
  .incoming() // relationships incoming to the element
  .filter(r => r.tags.includes('http')) // filter by tags
  .map(r => r.source) // get source elements

// Layouted views
const diagrams = await likec4.diagrams()

Check Typescript definitions for available methods.

Development

In root workspace:

pnpm install
pnpm build

cd packages/likec4
pnpm dev

Support

If there's a problem you're encountering or something you need help with, don't hesitate to take advantage of my Priority Support service where you can ask me questions in an exclusive forum. I'm well-equipped to assist you with this project and would be happy to help you out! 🙂