LikeC4 Vite Plugin

LikeC4 Vite Plugin allows you to embed views directly, without any pre-build/generate steps.
The plugin automatically generates all the necessary code to render the views in your application, with Hot Module Replacement (HMR) supported.

This is useful for building documentation, tutorials, or any other application where you want to include diagrams.

Guide

Create Vite project
Section titled “Create Vite project”

To get started, we will need to create a new Vite project using react-ts template.
- npm
- pnpm
- yarn
- bun
# create a new project with npm npm create vite@latest -- --template react-ts
# create a new project with pnpm pnpm create vite@latest --template react-ts
# create a new project with yarn yarn create vite --template react-ts
# create a new project with bun bun create vite@latest --template react-ts
Install LikeC4
Section titled “Install LikeC4”

Add likec4 dependency:
- npm
- pnpm
- yarn
- bun
npm i -D likec4
pnpm add -D likec4
yarn add -D likec4
bun add -d likec4

Configure Vite

Add LikeC4 plugin to vite config:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
 import { LikeC4VitePlugin } from 'likec4/vite-plugin'

export default defineConfig({
  plugins: [
    react(),
     LikeC4VitePlugin(),
  ],
})

Add type references
Section titled “Add type references”

Add types reference to the vite-env.d.ts file
(or create new one, like src/likec4.d.ts)
src/vite-env.d.ts
```
/// <reference types="vite/client" />
 /// <reference types="likec4/vite-plugin-modules" />
```
Another option is to add to the tsconfig.json:
tsconfig.json
```
{
  "compilerOptions": {
    "types": [
      "likec4/vite-plugin-modules"
    ]
  }
}
```

Add LikeC4 model

Create src/tutorial.c4 and copy the following model from tutorial:

1
// Tutorial - https://likec4.dev/tutorial/
2

3
specification {
4
  element actor
5
  element system
6
  element component
7
}
8

9
model {
10
  customer = actor 'Customer' {
11
    description 'The regular customer of the system'
12
  }
44 collapsed lines
13

14
  saas = system 'Our SaaS' {
15
    component ui 'Frontend' {
16
      description 'Nextjs application, hosted on Vercel'
17
      style {
18
        icon tech:nextjs
19
        shape browser
20
      }
21
    }
22
    component backend 'Backend Services' {
23
      description '
24
        Implements business logic
25
        and exposes as REST API
26
      '
27
    }
28

29
    // UI requests data from the Backend
30
    ui -> backend 'fetches via HTTPS'
31
  }
32

33
  // Customer uses the UI
34
  customer -> ui 'opens in browser'
35
  customer -> saas 'enjoys our product'
36
}
37

38
views {
39

40
  view index {
41
    title 'Landscape view'
42

43
    include *
44
  }
45

46
  view saas of saas {
47
    include *
48

49
    style * {
50
      opacity 25%
51
    }
52
    style customer {
53
      color muted
54
    }
55
  }
56

57
}

Use LikeC4 view in your app

Change the src/main.tsx file and import LikeC4 view from the likec4:react module:

import { createRoot } from 'react-dom/client'
import { LikeC4View } from 'likec4:react'

createRoot(document.getElementById('root')!).render(
  <LikeC4View viewId='index' />
)

Start vite dev server
Section titled “Start vite dev server”
- npm
- pnpm
- yarn
- bun
npm run dev
pnpm run dev
yarn run dev
bun run dev
Open the browser and navigate to http://localhost:5173/.
You should see the LikeC4 diagram rendered in your app.

Plugin

Options

Option	Description
`workspace`	directory with source files (defaults to vite root)
`printErrors`	if model is invalid, errors are reported to the logger (default `true`)
`throwIfInvalid`	fails with rejected promise if model is invalid (default `false`)
`graphviz`	`wasm` (default) or `binary` - use local binaries of Graphviz (“dot”) or bundled WASM

Multi-project workspaces

If you have multiple projects in your workspace:

// where `project-a` and `project-b` are the names of your projects
import { LikeC4View as ProjectA_LikeC4View } from 'likec4:react/project-a'
import { LikeC4View as ProjectB_LikeC4View } from 'likec4:react/project-b'

const example = () => (
  <>
    <ProjectA_LikeC4View viewId='index' />
    <ProjectB_LikeC4View viewId='index' />
  </>
)

Usage with API

It is also possible to initiate using LikeC4 API:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { LikeC4 } from 'likec4'
import { LikeC4VitePlugin } from 'likec4/vite-plugin'

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

export default defineConfig({
  plugins: [
    react(),
    LikeC4VitePlugin({
      languageServices,
    }),
  ],
})

Virtual modules

Other modules are available to get access to the model:

// For multi-project workspaces
import { projects } from 'likec4:projects'

// Pick first one (default)
import { useLikeC4Views, useLikeC4View } from 'likec4:single-project'

// Project by name
import { useLikeC4Views, useLikeC4View } from 'likec4:model/project-a'

// Other modules
import { loadDotSources } from 'likec4:dot'
import { mmdSource } from 'likec4:mmd/project-a'

Complete list - vite-plugin/modules.d.ts

Usage

Here are some examples of how to use the plugin with different frameworks

With Astro

You can use LikeC4VitePlugin with Astro and Starlight documentation tool as well.
Configure Astro:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import { LikeC4VitePlugin } from 'likec4/vite-plugin'

export default defineConfig({
  integrations: [
    starlight({
      title: 'Your architecture docs site',
    }),
  ],
  vite: {
    plugins: [
      LikeC4VitePlugin({}),
    ],
  },
});

To use React components, first you need to wrap them in astro components:

---
import { LikeC4View as ReactLikeC4View, type LikeC4ViewId } from 'likec4:react';
interface Props {
  viewId: LikeC4ViewId;
}
const { viewId } = Astro.props
---

<ReactLikeC4View viewId={viewId} client:only="react">
</ReactLikeC4View>

Then you can use in markdown:

---
title: Welcome to my docs
---

import LikeC4View from '../../components/LikeC4View.astro';

## Introduction

This is an example of using LikeC4 in your documentation

<LikeC4View viewId="index" />

With Next.js

For Next.js (since it does not use Vite), there is a workaround - library mode:
Vite will generate a bundled library with likec4 diagrams, that you can import from your Next.js app.

Export everything from likec4:react:

export * from 'likec4:react'

Configure Vite:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { LikeC4VitePlugin } from 'likec4/vite-plugin'

export default defineConfig({
  build: {
    // Build views to 'lib' directory
    outDir: 'lib',
    lib: {
      entry: 'src/likec4/index.tsx',
    },
    rollupOptions: {
      // make sure to externalize deps that shouldn't be bundled
      // to avoid code duplication
      external: [
        'react',
        'react-dom',
        'react/jsx-runtime',
        'react/jsx-dev-runtime',
        'react-dom/client',
      ],
    },
  },
  plugins: [
    react(),
    LikeC4VitePlugin(),
  ],
})

Run vite build and import outputs from your Next.js app:

import { LikeC4View } from '../lib'

export default function Home() {
  return (
    <LikeC4View viewId="index" />
  )
}

You can run vite build --watch as a background process to watch for changes in likec4 source files.