> For the complete documentation index, see [llms.txt](https://boxlang-ide.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang-ide.ortusbooks.com/vscode/project-configuration.md).

# Project Configuration

The BoxLang extension reads project configuration from `boxlang.json` files placed at the workspace root (or any ancestor directory). This file defines virtual path mappings, classpaths, module directories, and more.

{% hint style="info" %}
`boxlang.json` supports `//` and `/* */` comments for documentation within the file.
{% endhint %}

***

## Quick Start

Create a `boxlang.json` at your workspace root:

```json
{
  "mappings": {
    "/models": "models",
    "/views": "views"
  },
  "modulesDirectory": [
    "boxlang_modules"
  ]
}
```

This tells the LSP that the logical path `/models` maps to the `models/` directory in your workspace.

***

## Configuration Reference

### Top-Level Keys

| Key                | Type       | Default                | Description                                                                                                                                                  |
| ------------------ | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mappings`         | `object{}` | `{"/": "${user-dir}"}` | Virtual path prefix to filesystem path mappings. The key is the logical prefix (must start with `/`) and the value is a relative or absolute directory path. |
| `classPaths`       | `string[]` | `[]`                   | Additional directories to include in the classpath for type resolution. Paths may be absolute or relative to `boxlang.json`.                                 |
| `modulesDirectory` | `string[]` | `["boxlang_modules"]`  | Directories containing BoxLang modules. Defaults to `boxlang_modules/` relative to `boxlang.json`. Paths may be absolute or relative.                        |

### Mappings

Mappings are the core of project configuration. They tell the LSP how to resolve logical module paths (like `/models`, `/coldbox`) to actual filesystem locations.

```json
{
  "mappings": {
    "/": "src",
    "/models": "src/models",
    "/views": "src/views",
    "/coldbox": "/absolute/path/to/coldbox"
  }
}
```

**Rules:**

* Keys must start with `/`
* Values can be relative (to `boxlang.json`) or absolute
* The `/` mapping defines the root of your application

{% hint style="info" %}
`boxlang.json` mappings are used by both navigation features and mapping-dependent diagnostics such as `invalidExtends`.
{% endhint %}

### ClassPaths

Use `classPaths` to include additional directories for Java class resolution:

```json
{
  "classPaths": [
    "lib",
    "/usr/local/share/java-libs"
  ]
}
```

### Modules Directory

BoxLang modules are located in standardized directories:

```json
{
  "modulesDirectory": [
    "boxlang_modules",
    "/opt/boxlang/shared-modules"
  ]
}
```

The default `boxlang_modules/` directory is relative to your `boxlang.json` file.

***

## Variable Expansion

Paths support variable expansion using the `${variable}` syntax:

| Variable             | Expands to                                                |
| -------------------- | --------------------------------------------------------- |
| `${boxlang-home}`    | The active BoxLang Home directory (default: `~/.boxlang`) |
| `${user-dir}`        | The user's home directory                                 |
| `${env.VAR}`         | The value of the environment variable `VAR`               |
| `${env.VAR:default}` | The value of `VAR`, or `default` if not set               |

### Example

```json
{
  "mappings": {
    "/coldbox": "${boxlang-home}/modules/coldbox",
    "/models": "${env.APP_MODELS:src/models}"
  }
}
```

***

## VS Code Integration

### boxlang.json Schema Validation

The extension provides JSON schema validation for `boxlang.json` files. This gives you:

* **Autocomplete** for top-level keys
* **Validation** of value types
* **Hover documentation** for each setting
* **Error highlighting** for invalid values

The schema matches any file named `boxlang.json` (e.g., `boxlang.json`, `my-boxlang.json`).

### Workspace Mappings Override

The VS Code setting `boxlang.mappings` allows you to override project mappings directly in your editor settings:

```json
{
  "boxlang.mappings": {
    "/models": "/absolute/path/to/models",
    "/custom": "./relative/path"
  }
}
```

{% hint style="warning" %}
`boxlang.mappings` takes **precedence** over `boxlang.json` mappings. Use it for personal overrides that shouldn't be committed to the project.
{% endhint %}

### Mapping Resolution Order

When the language server resolves virtual paths for diagnostics and symbol lookup, it merges mappings from several sources:

1. ColdBox implicit module mappings
2. `boxlang.json`
3. `.bxlint.json`
4. The nearest `Application.bx` or `Application.cfc`
5. VS Code `boxlang.mappings`

This means project mappings can be refined for analysis in `.bxlint.json`, overridden locally in editor settings, or supplied directly from application-level static `this.mappings` entries.

{% hint style="success" %}
Saving `boxlang.json`, `Application.bx`, or `Application.cfc` causes the LSP to refresh mapping-dependent diagnostics for open documents without restarting the language server.
{% endhint %}

***

## Complete Example

A comprehensive `boxlang.json` for a ColdBox application:

```json
{
  "mappings": {
    "/": "src",
    "/coldbox": "${boxlang-home}/modules/coldbox",
    "/testbox": "${boxlang-home}/modules/testbox"
  },
  "classPaths": [
    "lib",
    "lib/java"
  ],
  "modulesDirectory": [
    "boxlang_modules",
    "${boxlang-home}/modules"
  ]
}
```

***

## Relationship to Other Config Files

| File                    | Purpose                                           |
| ----------------------- | ------------------------------------------------- |
| `boxlang.json`          | Project structure — mappings, classpaths, modules |
| `.bxlint.json`          | Static analysis rules and file filters            |
| `.bxformat.json`        | Code formatting rules                             |
| VS Code `settings.json` | Editor-level overrides and IDE preferences        |

{% hint style="info" %}
`.bxlint.json` can also define `mappings` used specifically for lint analysis, and the nearest `Application.bx` / `Application.cfc` can contribute static `this.mappings` entries for resolution. See [Linting](/language-tools/linting.md) for the analysis-specific behavior and quick fixes.
{% endhint %}

***

## Related Pages

{% content-ref url="/pages/IrW4QLiDssODkp3WA2Gy" %}
[Settings Reference](/vscode/settings-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/VSJK5BN8JfZ1nH6gWa4L" %}
[Version Management](/vscode/version-management.md)
{% endcontent-ref %}

{% content-ref url="/pages/YnKdTWzleHOkyLjM4tql" %}
[Linting](/language-tools/linting.md)
{% endcontent-ref %}

{% content-ref url="/pages/v8TCDnWb6DfLwQdPxEHQ" %}
[Formatting](/language-tools/formatting.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang-ide.ortusbooks.com/vscode/project-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.