# Multi-projects


Sometimes you may want to split your LikeC4 model into multiple ones, based on domains, teams, or any other criteria.

You can do this by creating multiple projects in your workspace and linking them together.  
You can also use this feature to share your model with other teams or projects.

Create `likec4.config.json` files in the folders you want to be projects:

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

Projects can be nested.  
In this case, files from the nested project are not part of the parent project.

<FileTree>
- cloud
  - likec4.config.json
  - service1.c4
  - service2.c4
  - nested
    - likec4.config.json
    - service3.c4 // this will be part of the 'nested' project, not the 'cloud' project
</FileTree>


## Import elements

You can import elements from other projects by using the `import` keyword.

```likec4
import { serviceA } from 'projectA'

model {
  serviceB = service {
    -> serviceA.api 'calls serviceA'
  }
}
```

<Aside type='caution' title="Limitations">
At the moment, the following limitations apply:
- Referenced projects must be loaded in the same workspace
- Only top-level **model** elements can be imported
</Aside>

## Share specification

You can share specification files (or any other LikeC4 sources) across multiple projects using the `include` configuration option.

### Using include paths

Add an `include` configuration to your project to include files from directories outside the project folder:

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

<FileTree>
- shared
  - specs.c4
  - common-styles.c4
- cloud
  - likec4.config.json
  - services.c4
  - ...
- externals
  - likec4.config.json
  - amazon.c4
  - ...
</FileTree>

Both `cloud` and `externals` projects can include the shared specification:

```json title="cloud/likec4.config.json"
{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "cloud",
  "include": {
    "paths": ["../shared"]
  }
}
```

```json title="externals/likec4.config.json"
{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "externals",
  "include": {
    "paths": ["../shared"]
  }
}
```

### Include configuration

The `include` configuration accepts an object with the following properties:

```json
{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "my-project",
  "include": {
    "paths": ["../shared", "../common/specs"],
    "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)

<Aside type='tip' title="Performance optimization">
Use `maxDepth` to limit deep directory traversal, and `fileThreshold` to detect when you're accidentally including large directories.  
If you see warnings about slow loading, consider reducing `maxDepth` or being more specific with your include paths.
</Aside>

<Aside type='tip' title="Path resolution">
Include paths are relative to the project folder (the folder containing the config file).  
LikeC4 recursively scans the included directories for `.c4` files.
</Aside>

<Aside type='caution' title="Path requirements">
Include paths must be relative paths. Absolute paths, drive letters (like `C:\`), and URLs are not allowed.
</Aside>

### Using symlinks (alternative)

Alternatively, you can use symlinks to share files:

<FileTree>
- shared
  - specs.c4
- cloud
  - specs.c4 // -> ../shared/specs.c4
  - likec4.config.json
  - ...
- externals
  - specs.c4 // -> ../shared/specs.c4
  - likec4.config.json
  - ...
</FileTree>

<Aside type='note'>
The `include` configuration is generally preferred over symlinks as it's more portable and easier to manage.
</Aside>