Project config

To define a project, create a likec4.config.json file in the folder.
All files in the folder (and subfolders) will be part of this project:

• Directoryexternals

  • amazon.c4
  • …
• Directoryservices

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

Configuration

The likec4.config.json file must have the name of the project.

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

The name must be unique if you use multiple projects.

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

Note

You can use these names for the config file:

• .likec4rc
• .likec4.config.json
• likec4.config.json

LikeC4 interprets any file as JSON5

You can also use these names:

• likec4.config.js
• likec4.config.mjs
• likec4.config.ts
• likec4.config.mts

See Programmatic config for more information.

Extend styles

If you want to share styles across multiple projects, you can use extends in JSON configs. 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"
      }
    }
  }
}

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 .c4 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)
• fileThreshold - Warn if more than this many files are loaded (default: 30)

Note

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

For more details on sharing files between projects, 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”. bootstrap: icons are excluded.

To disable this behavior:

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

Implicit views

By default, LikeC4 automatically generates scoped views for elements that don’t have explicitly defined views. This enables drill-down navigation out of the box — clicking on an element in any diagram navigates to its auto-generated scoped view (equivalent to view of element { include * }).

To disable this behavior:

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

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.

Use the likec4.config.json to add an imageAliases field:

{
  "$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

In the example above the externals.c4 is a nested file, but the aliasing works based on the project root.

Naming Rules

When using image aliases, keep the following rules in mind:

• Aliases must start with @ and can include letters, numbers, and underscores.
• The alias must be unique within the project.
• The alias can point to a relative or absolute path.

Defaults

When no LikeC4 configuration file is found, or when no imageAliases field is found, LikeC4 uses the following defaults:

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

Simply override the @ to change the default location.

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

Styles customization

LikeC4 provides advanced style customization capabilities.

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.

{
  "$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"
      }
    }
  }
}

Advanced Customization

For even more advanced customization including custom React components, shapes, and overlays, check out the example-customization repository which demonstrates:

• Custom Element Nodes: Override default node rendering with custom React components
• Custom Shapes: Implement unique visual representations using SVG and drawing libraries
• Custom Overlays: Create interactive dialogs for displaying detailed information
• Enhanced Interactions: Add custom buttons, toolbars, and interactive behaviors