Project config

A project is a set of LikeC4 source files (.c4, .likec4, .like-c4) with its own model and views.
To define a project, create a config file in a folder.
All source files in this folder and its subfolders are part of the project:

• Directoryexternals

  • amazon.c4
  • …
• Directoryservices

  • service1.c4
  • service2.c4
  • …
• specification.c4
• likec4.config.json

The config file is optional.
Without it, all source files in the workspace belong to one project named default, with default settings.
Add a config file to name the project, change the options below, or split the model into multiple projects.

Config file

LikeC4 looks for these file names:

• likec4.config.json, .likec4.config.json or .likec4rc: JSON config. LikeC4 parses it as JSON5, so comments and trailing commas are allowed.
• likec4.config.ts, .mts, .cts, .js, .mjs or .cjs: see TypeScript config.

Use one config file per folder.
To choose between JSON and TypeScript, see Config files.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "title": "Project Title",         // optional
  "contactPerson": "Jane Doe",      // optional
  "metadata": {                     // optional
    "owner": "platform-team",
    "domain": "payments"
  }
}

Use metadata to store arbitrary project-level key-value data that can be consumed by tooling.

Project name

name identifies the project. Other projects use it to import elements.

• It must be unique in the workspace.
• It cannot be default: this name is reserved for files outside of any project.
• It cannot contain ., @ or #. Use letters, digits, _ and -.

If you omit name, LikeC4 uses the name of the folder.
The JSON schema still marks name as required, so set it explicitly.

TypeScript config

You can write the config in TypeScript or JavaScript.
Import defineConfig from likec4/config and export the result as default:

likec4.config.ts

import { defineConfig } from 'likec4/config'

export default defineConfig({
  name: 'my-project',
  title: 'My Project',
  exclude: ['**/node_modules/**', '**/.cache/**'],
  include: {
    paths: ['../shared'],
  },
  imageAliases: {
    '@': './images',
  },
})

The file can be named likec4.config.ts, likec4.config.mts, likec4.config.cts, likec4.config.js, likec4.config.mjs or likec4.config.cjs.
LikeC4 loads it directly, without a build step.
It provides likec4/config itself, so you do not need to install likec4 to load the file. Install it to get type checking in your editor.
The smaller package @likec4/config exports the same helpers.

A TypeScript config accepts all options from this page, including styles.
Choose it when you need code:

• custom generators, which are functions and cannot be written in JSON;
• styles shared as a module or a package (defineStyle, defineTheme, defineThemeColor), or values computed in code.

extends works only in JSON configs, see below.

Extend styles

To share styles across multiple projects, use extends in a JSON config. extends can be a string or an array of strings. Each path is resolved relative to the config file that declares it, and extends can be recursive. LikeC4 merges only the styles section (in order); all other fields come from the root config.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "extends": [
    "../shared/base-config.json",
    "../shared/theme-config.json"
  ],
  "styles": {
    "defaults": {
      "relationship": {
        "arrow": "vee"
      }
    }
  }
}

A TypeScript config ignores extends. Import the shared styles instead. Define them with defineStyle in a separate file or package:

@your-org/likec4-theme

import { defineStyle } from 'likec4/config'

export default defineStyle({
  theme: {
    colors: {
      primary: '#FF6B6B',
    },
  },
})

likec4.config.ts

import { defineConfig } from 'likec4/config'
import styles from '@your-org/likec4-theme'

export default defineConfig({
  name: 'my-project',
  styles,
})

defineTheme and defineThemeColor help to define parts of the styles in the same way.

Include additional directories

You can include LikeC4 source files from directories outside the project folder by adding an include configuration to the config file. This is useful for sharing specifications, common styles, or other model files across multiple projects.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "include": {
    "paths": [
      "../shared",
      "../common/specs"
    ]
  }
}

• Directoryshared

  • specs.c4
  • common-styles.c4
• Directorycommon

  • Directoryspecs

    • base-elements.c4
• Directorymy-project

  • likec4.config.json
  • model.c4
  • …

Paths are relative to the project folder (the folder containing the config file).
LikeC4 recursively scans the included directories for source files.

You can also configure the scanning behavior:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "include": {
    "paths": ["../shared"],
    "maxDepth": 5,
    "fileThreshold": 50
  }
}

• paths - Array of relative directory paths (required)
• maxDepth - Maximum directory depth to scan (default: 3, range: 1-20). Use it to limit deep directory traversal.
• fileThreshold - Warn if more than this many files are loaded (default: 30, range: 1-10000). Use it to detect large directories included by mistake.

Note

Include paths must be relative paths. Absolute paths (like /usr/share), drive letters (like C:\), and URLs are not allowed.

exclude patterns of the project apply to the included directories too.
To share files between projects this way, see Multi-projects.

Exclude files

By default, LikeC4 recursively scans in the project folder.
You can exclude files by adding an exclude array to the config file.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "exclude": [
    "**/node_modules/**"
  ]
}

If no exclude pattern is provided, LikeC4 uses ["**/node_modules/**"] as default.
The exclude pattern is the same as the one used by picomatch.

Infer technology from icon

By default, LikeC4 automatically derives a human-readable technology label from bundled icon names (aws:, azure:, gcp:, tech:) when technology is not explicitly set on the element or its kind.

For example, an element with icon tech:apache-flink gets technology “Apache Flink”, and icon aws:simple-storage-service gets “Simple Storage Service”. Generic bootstrap: and md: icons are excluded.

To disable this behavior:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "inferTechnologyFromIcon": false
}

Implicit views

LikeC4 can automatically generate scoped views for elements that don’t have explicitly defined views, enabling drill-down navigation — clicking on an element navigates to its auto-generated scoped view (equivalent to view of element { include * }). This feature is disabled by default.

To enable this behavior:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "implicitViews": true
}

Landing page

Configure what is shown when visiting the root URL of a generated static site. Use only one of redirect, include or exclude.

Redirect to the index view

Set redirect to true to go straight to the index view instead of showing the view grid:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "landingPage": {
    "redirect": true
  }
}

Filter views by inclusion

Show only specific views on the landing page grid, by view ID or tag (#tagName):

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "landingPage": {
    "include": ["cloud", "#overview"]
  }
}

Filter views by exclusion

Hide specific views from the landing page grid:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "landingPage": {
    "exclude": ["#internal", "legacy-backend"]
  }
}

Webapp export formats

Configure which export formats are available in the generated web application. When webapp.exportFormats is omitted, all webapp exports remain enabled. Use an empty array to remove the Export button.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "webapp": {
    "exportFormats": ["png", "jpg", "drawio"]
  }
}

Supported values are png, jpg, dot, d2, mmd, puml, and drawio. This setting affects the generated webapp only; CLI export commands are unchanged. For png and jpg, this removes the menu entries; direct image export routes used by screenshot automation remain available. In multi-project webapps, each project uses its own export format list.

Relationship browser scope

Configure the initial scope in the relationship browser. The allowed values are global and view. The default is view.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "webapp": {
    "relationshipsBrowser": {
      "defaultScope": "global"
    }
  }
}

A saved user preference takes precedence over defaultScope. The relationshipsScope URL parameter takes precedence over both the saved preference and defaultScope.

Manual layouts

When you save a manual layout of a view, LikeC4 stores it as a <view-id>.likec4.snap file.
By default, these files are in the .likec4 folder of the project.
Use manualLayouts.outDir to change the folder, relative to the project folder:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "manualLayouts": {
    "outDir": "layouts"
  }
}

Image aliases

When using local images in your LikeC4 model, you can create aliases for the folder your images are in to make them more readable and the files more transportable.

Add an imageAliases field to the config:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "imageAliases": {
    "@": "./images",
    "@root": "../../some-more-images"
  }
}

You can then use the alias in your model:

example

// ./amazon.c4
model {
  serviceA = service {
    icon: @/service-a.png
  }

  serviceB = service {
    icon: @root/service-b.png
  }
}

// ./externals/externals.c4
model {
  serviceC = service {
    icon: @/service-c.png
  }
}

• Directorysome-more-images

  • service-b.png
  • …
• Directorydocs

  • Directoryproject

    • Directoryimages

      • service-a.png
      • service-c.png
      • …
    • Directoryexternals

      • externals.c4
    • likec4.config.json
    • amazon.c4
    • …

Note

Alias paths are relative to the project folder, not to the source file. In the example above, externals/externals.c4 uses the same @ folder as amazon.c4.

Naming rules

• An alias starts with @, followed by letters, digits, _ or -.
• The path must be relative to the project folder. Absolute paths and URLs are not allowed.

Default alias

@ points to ./images, unless you override it.
To change the default location, set @:

{
  "imageAliases": {
    "@": "./my-images"
  }
}

Styles customization

Override the theme and the default styles of the project.
The same styles options work in a TypeScript config.

Theme overrides

You can override default theme colors and sizes by adding a styles.theme section to the config file. Each definition can be either a CSS value or a detailed object specifying color for specific parts.

Example of simple color definition:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "styles": {
    "theme": {
      "colors": {
        "primary": "#FF6B6B",
        "secondary": "rgba(37,99,235,1)",
      }
    },
  }
}

Example of detailed color definition:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "styles": {
    "theme": {
      "colors": {
        "muted": {
          "elements": {
            "fill": "#2563eb", // Background color
            "stroke": "#1d4ed8", // Border color
            "hiContrast": "#ffffff", // Title text color
            "loContrast": "#e2e8f0" // Description text color
          },
          "relationships": {
            "line": "#1d4ed8", // Line color
            "label": "#ffffff", // Label text color
            "labelBg": "rgba(37,99,235,0.1)" // Label background color
          }
        },
        // You can give detailed definitions for a custom color in your specification
        "custom-color-from-your-spec": {
          // ...
        }
      }
    },
  }
}

You can override sizes used in LikeC4:

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "styles": {
    "theme": {
      "sizes": {
        "md": {
          "width": 200,
          "height": 200
        },
        "lg": {
          "width": 300,
          "height": 300
        }
      }
    }
  }
}

Default styles

You can override default values for style properties by adding a styles.defaults section to the config file.
These values will be applied to all elements and relationships, unless properties are explicitly defined in the specification.

You can set the default routing for views with styles.defaults.view.routing.

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",
  "styles": {
    "defaults": {
      // Defaults for all elements
      "border": "dashed",
      "opacity": 100,
      "size": "md",
      "color": "primary", // theme color name

      // Defaults for groups
      "group": {
        "color": "primary",
        "opacity": 10,
        "border": "dashed"
      },

      // Defaults for relationships
      "relationship": {
        "color": "gray",
        "line": "dashed",
        "arrow": "normal"
      },

      // Defaults for views
      "view": {
        // Edge routing: "spline" (curved, default) or "ortho" (right-angle bends)
        // Override this default with routing or autoLayout in a view.
        "routing": "ortho"
      }
    }
  }
}

A view’s routing property or autoLayout routing parameter overrides styles.defaults.view.routing. See Edge routing for precedence and limitations.

To change UI components, not only colors and sizes, see UI customization.