Configuration

Configure module settings, dependencies, and runtime overrides

Module settings are defined in configure() and can be overridden at runtime through boxlang.json. Modules can also declare dependencies on other modules.

Module Settings

Define settings in your descriptor's configure() method:

ModuleConfig.bx

function configure() {
    settings = {
        apiKey: "",
        timeout: 30,
        debug: false,
        endpoints: {
            primary: "https://api.example.com/v1",
            fallback: "https://api.example.com/v2"
        }
    };
}

Java IModuleConfig

Runtime Overrides

Users can override module settings in boxlang.json:

{
  "modules": {
    "myModule": {
      "enabled": true,
      "settings": {
        "apiKey": "sk-abc123",
        "debug": true
      }
    }
  }
}

Merge Behavior

Runtime settings are deep-merged on top of configure() defaults:

configure() setting	boxlang.json override	Effective value
apiKey: ""	apiKey: "sk-abc123"	"sk-abc123" (overridden)
timeout: 30	(not set)	30 (default preserved)
debug: false	debug: true	true (overridden)
endpoints.primary	(not set)	"https://api..." (nested preserved)

Disabling Modules

Modules can be disabled via runtime config:

{
  "modules": {
    "myModule": {
      "enabled": false
    }
  }
}

The module is still discovered but skipped during registration — no BIFs, components, or services are loaded.

Accessing Settings

Access module settings from anywhere:

// From ModuleConfig.bx
var timeout = settings.timeout

// From module code
var moduleService = boxRuntime.getModuleService()
var settings = moduleService.getModuleSettings( "myModule" )
var timeout = settings.timeout

Dependencies

Declare module dependencies to control activation order:

ModuleConfig.bx

class {
    this.dependencies = [ "bx-plus", "bx-compat-cfml" ];
}

Java @BoxModule

How dependencies work:

• Dependencies are activated before the dependent module
• Resolution is recursive (a dependency's dependencies are also activated first)
• Missing dependencies cause a warning but don't prevent activation
• Use box.json dependencies for ForgeBox package dependencies

this.dependencies controls activation order, while box.json dependencies controls package installation. Both should list your module's dependencies.

Inter-Module Communication

Check for and interact with other loaded modules:

function onLoad() {
    var moduleService = boxRuntime.getModuleService()

    // Check if another module is loaded
    if ( moduleService.hasModule( "bx-spreadsheet" ) ) {
        var spreadsheetSettings = moduleService.getModuleSettings( "bx-spreadsheet" )
        // Read or modify (use cautiously)
    }
}

Next Steps

• Advanced Collaboration — System settings providers and class resolvers
• Packaging & Publishing — Build and distribute your module
• Testing — TestBox integration and CI/CD patterns