# 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:

<FileTree>
- externals
  - amazon.c4
  - ...  
- services
  - service1.c4
  - service2.c4
  - ...  
- specification.c4
- **likec4.config.json**
</FileTree>

## Configuration

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


```jsonc
{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "project-name",  // required
  "title": "Project Title" // optional
}
```

The name must be unique if you use [multiple projects](/dsl/config/multi-projects).

:::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](/dsl/config/programmatic) for more information.
:::

## 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.

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

<FileTree>
- shared
  - specs.c4
  - common-styles.c4
- common
  - specs
    - base-elements.c4
- my-project
  - **likec4.config.json**
  - model.c4
  - ...
</FileTree>

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:

```json
{
  "$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](/dsl/config/multi-projects#share-specification).

## Exclude files

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

```json
{
  "$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](https://github.com/micromatch/picomatch).  

## 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:

```json
{
  "$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:

```likec4 title="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
  }
}
```

<FileTree>
- some-more-images
  - service-b.png
  - ...
- docs
  - project
    - images
      - service-a.png
      - service-c.png
      - ...
    - externals
      - externals.c4
    - likec4.config.json
    - amazon.c4
    - ...
</FileTree>

:::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:

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

Simply override the `@` to change the default location.

```json
{
  "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:

```jsonc
{
  "$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:

```jsonc
{
  "$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:

```jsonc
{
  "$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.

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

<AdvancedCustomizationTip />