Project Configuration

How to configure BoxLang projects — boxlang.json structure, mappings, classpaths, modules, variable expansion, and VS Code integration.

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.

boxlang.json supports // and /* */ comments for documentation within the file.

---

Quick Start

Create a boxlang.json at your workspace root:

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

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

boxlang.json mappings are used by both navigation features and mapping-dependent diagnostics such as invalidExtends.

ClassPaths

Use classPaths to include additional directories for Java class resolution:

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

Modules Directory

BoxLang modules are located in standardized directories:

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

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

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

boxlang.mappings takes precedence over boxlang.json mappings. Use it for personal overrides that shouldn't be committed to the project.

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.

Saving boxlang.json, Application.bx, or Application.cfc causes the LSP to refresh mapping-dependent diagnostics for open documents without restarting the language server.

---

Complete Example

A comprehensive boxlang.json for a ColdBox application:

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

.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 for the analysis-specific behavior and quick fixes.

---

Related Pages

Settings ReferenceVersion ManagementLintingFormatting