Coldbox Configuration

Use this skill when configuring a ColdBox application in ColdBox.cfc, setting up environments, managing module settings, defining datasources, configuring logging with LogBox, setting up caching with CacheBox, or wiring dependencies with WireBox settings.

ColdBox 5b66a45 14.7 KB Updated Sep 17, 2026

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add coldbox/coldbox-configuration

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/coldbox/coldbox-configuration.svg)](https://skillmd.com/skills/coldbox/coldbox-configuration)

Trust & safety

Audits pending

Not yet audited · commit 5b66a45

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

ColdBox Configuration

When to Use This Skill

Use this skill when configuring a ColdBox application via config/ColdBox.cfc — the master application configuration file.

Language Mode Reference

Examples use BoxLang (.bx) syntax by default. Adapt for your target language:

Concept	BoxLang (`.bx`)	CFML (`.cfc`)
Class declaration	`class [extends="..."] {`	`component [extends="..."] {`
DI annotation	`@inject` above `property name="svc";`	`property name="svc" inject="svc";`
View templates	`.bxm` suffix	`.cfm` / `.cfml` suffix
Tag prefix	`<bx:if>`, `<bx:output>`, `<bx:set>`	`<cfif>`, `<cfoutput>`, `<cfset>`

CFML Compat Mode: With BoxLang + CFML Compat module, .bx and .cfc files coexist freely. BoxLang-native classes use class {} (.bx files); CFML-compat classes use component {} (.cfc files).

Core Concepts

ColdBox.cfc contains sections for:

coldbox — core framework settings
environments — environment-specific overrides
modules — module settings per module
interceptors — registered interceptors
logbox — LogBox logging configuration
cachebox — CacheBox cache configuration
wirebox — WireBox DI configuration

Full ColdBox.cfc Template

class ColdBox extends coldbox.system.Coldbox {

    function configure() {

        // =============================================
        // COLDBOX SETTINGS
        // =============================================
        coldbox = {
            // Application name
            appName              : "My ColdBox Application",
            appMapping           : "root",

            // Application reloading
            reinitPassword       : getSystemSetting( "REINIT_PASSWORD", "supersecret" ),
            reinitKey            : "reinit",

            // Default handler and view
            defaultHandler       : "main",
            defaultAction        : "index",
            defaultLayout        : "Main",
            defaultView          : "main/index",

            // Request Defaults
            requestContextDecorator : "",
            controllerDecorator     : "",

            // Custom interception points
            customInterceptionPoints : [
                "onUserLogin",
                "onUserLogout",
                "onOrderPlaced"
            ],

            // Exception handler
            exceptionHandler     : "main.onException",

            // Invalid event handler
            invalidEventHandler  : "main.onInvalidEvent",

            // Request timeout
            requestTimeout       : 60,

            // ColdBox settings
            handlersIndexAutoReload  : true,          // Development only
            modulesExternalLocation  : [ "modules" ]
        }

        // =============================================
        // ENVIRONMENT DETECTION
        // =============================================
        environments = {
            development : "localhost,127.0.0.1,^local",
            staging     : "staging.example.com",
            production  : "example.com"
        }

        // =============================================
        // LAYOUTS
        // =============================================
        layoutSettings = {
            defaultLayout : "Main",
            defaultView   : "main/index"
        }

        // =============================================
        // MODULES
        // =============================================
        moduleSettings = {
            // CBSecurity settings
            cbsecurity : {
                userService    : "UserService",
                jwtSettings    : {
                    secretKey  : getSystemSetting( "JWT_SECRET", generateSecretKey( "AES", 256 ) ),
                    expiration : 60
                }
            },
            // CBAuth settings
            cbauth : {
                userServiceClass : "UserService"
            },
            // CBI18N settings
            cbi18n : {
                defaultLocale  : "en_US",
                resourceBundles : {
                    main : "#appMapping#/includes/i18n/main"
                }
            }
        }

        // =============================================
        // INTERCEPTORS
        // =============================================
        interceptors = [
            {
                class  : "#appMapping#.interceptors.AppInterceptor",
                name   : "AppInterceptor"
            }
        ]

        // =============================================
        // LOGBOX
        // =============================================
        logbox = {
            // Appenders
            appenders : {
                // Console appender (development)
                console : {
                    class      : "coldbox.system.logging.appenders.ConsoleAppender",
                    levelMin   : "DEBUG",
                    levelMax   : "FATAL"
                },
                // Rolling file appender
                rolling : {
                    class      : "coldbox.system.logging.appenders.RollingFileAppender",
                    levelMin   : "WARN",
                    levelMax   : "FATAL",
                    properties : {
                        filePath  : "#getDirectoryFromPath( getBaseTemplatePath() )#logs",
                        fileName  : "app",
                        fileMaxSize : 5000,
                        fileMaxArchives : 2
                    }
                }
            },
            // Root logger
            root : { levelMin : "WARN", levelMax : "FATAL", appenders : "rolling" },
            // Category loggers
            categories : {
                // App debug
                "root"   : { levelMin : "INFO", levelMax : "DEBUG", appenders : "console" }
            }
        }

        // =============================================
        // CACHEBOX
        // =============================================
        cachebox = {
            // Configuration file
            configFile : "#appMapping#.config.CacheBox"
        }

        // =============================================
        // WIREBOX
        // =============================================
        wirebox = {
            enabled      : true,
            singletonReload : true,
            binder       : "#appMapping#.config.WireBox"
        }
    }

    // =============================================
    // ENVIRONMENT-SPECIFIC OVERRIDES
    // =============================================

    function development() {
        coldbox.handlersIndexAutoReload = true
        coldbox.reinitPassword          = ""
        coldbox.customErrorTemplate     = "/coldbox/system/exceptions/debugPanel.cfm"
    }

    function staging() {
        coldbox.customErrorTemplate = "/coldbox/system/exceptions/customError.cfm"
    }

    function production() {
        coldbox.handlersIndexAutoReload = false
        coldbox.reinitPassword          = getSystemSetting( "REINIT_PASSWORD", "changeme" )
        coldbox.customErrorTemplate     = "/coldbox/system/exceptions/customError.cfm"
    }
}

CFML (.cfc):

component extends="coldbox.system.Coldbox" {

    function configure() {

        // =============================================
        // COLDBOX SETTINGS
        // =============================================
        coldbox = {
            // Application name
            appName              : "My ColdBox Application",
            appMapping           : "root",

            // Application reloading
            reinitPassword       : getSystemSetting( "REINIT_PASSWORD", "supersecret" ),
            reinitKey            : "reinit",

            // Default handler and view
            defaultHandler       : "main",
            defaultAction        : "index",
            defaultLayout        : "Main",
            defaultView          : "main/index",

            // Request Defaults
            requestContextDecorator : "",
            controllerDecorator     : "",

            // Custom interception points
            customInterceptionPoints : [
                "onUserLogin",
                "onUserLogout",
                "onOrderPlaced"
            ],

            // Exception handler
            exceptionHandler     : "main.onException",

            // Invalid event handler
            invalidEventHandler  : "main.onInvalidEvent",

            // Request timeout
            requestTimeout       : 60,

            // ColdBox settings
            handlersIndexAutoReload  : true,          // Development only
            modulesExternalLocation  : [ "modules" ]
        }

        // =============================================
        // ENVIRONMENT DETECTION
        // =============================================
        environments = {
            development : "localhost,127.0.0.1,^local",
            staging     : "staging.example.com",
            production  : "example.com"
        }

        // =============================================
        // LAYOUTS
        // =============================================
        layoutSettings = {
            defaultLayout : "Main",
            defaultView   : "main/index"
        }

        // =============================================
        // MODULES
        // =============================================
        moduleSettings = {
            // CBSecurity settings
            cbsecurity : {
                userService    : "UserService",
                jwtSettings    : {
                    secretKey  : getSystemSetting( "JWT_SECRET", generateSecretKey( "AES", 256 ) ),
                    expiration : 60
                }
            },
            // CBAuth settings
            cbauth : {
                userServiceClass : "UserService"
            },
            // CBI18N settings
            cbi18n : {
                defaultLocale  : "en_US",
                resourceBundles : {
                    main : "#appMapping#/includes/i18n/main"
                }
            }
        }

        // =============================================
        // INTERCEPTORS
        // =============================================
        interceptors = [
            {
                class  : "#appMapping#.interceptors.AppInterceptor",
                name   : "AppInterceptor"
            }
        ]

        // =============================================
        // LOGBOX
        // =============================================
        logbox = {
            // Appenders
            appenders : {
                // Console appender (development)
                console : {
                    class      : "coldbox.system.logging.appenders.ConsoleAppender",
                    levelMin   : "DEBUG",
                    levelMax   : "FATAL"
                },
                // Rolling file appender
                rolling : {
                    class      : "coldbox.system.logging.appenders.RollingFileAppender",
                    levelMin   : "WARN",
                    levelMax   : "FATAL",
                    properties : {
                        filePath  : "#getDirectoryFromPath( getBaseTemplatePath() )#logs",
                        fileName  : "app",
                        fileMaxSize : 5000,
                        fileMaxArchives : 2
                    }
                }
            },
            // Root logger
            root : { levelMin : "WARN", levelMax : "FATAL", appenders : "rolling" },
            // Category loggers
            categories : {
                // App debug
                "root"   : { levelMin : "INFO", levelMax : "DEBUG", appenders : "console" }
            }
        }

        // =============================================
        // CACHEBOX
        // =============================================
        cachebox = {
            // Configuration file
            configFile : "#appMapping#.config.CacheBox"
        }

        // =============================================
        // WIREBOX
        // =============================================
        wirebox = {
            enabled      : true,
            singletonReload : true,
            binder       : "#appMapping#.config.WireBox"
        }
    }

    // =============================================
    // ENVIRONMENT-SPECIFIC OVERRIDES
    // =============================================

    function development() {
        coldbox.handlersIndexAutoReload = true
        coldbox.reinitPassword          = ""
        coldbox.customErrorTemplate     = "/coldbox/system/exceptions/debugPanel.cfm"
    }

    function staging() {
        coldbox.customErrorTemplate = "/coldbox/system/exceptions/customError.cfm"
    }

    function production() {
        coldbox.handlersIndexAutoReload = false
        coldbox.reinitPassword          = getSystemSetting( "REINIT_PASSWORD", "changeme" )
        coldbox.customErrorTemplate     = "/coldbox/system/exceptions/customError.cfm"
    }
}

Environment Variables Pattern

// Using CFML/BoxLang environment variable helper
function configure() {
    vars.datasource = getSystemSetting( "DB_DSN", "myapp" )

    coldbox = {
        appName      : getSystemSetting( "APP_NAME", "My App" ),
        reinitPassword : getSystemSetting( "REINIT_PASSWORD", "" )
    }
}

Module Settings

// Override any module setting from ColdBox.cfc
moduleSettings = {
    // Override cbsecurity module settings
    cbsecurity : {
        firewall : {
            rules : [
                {
                    secureList : "admin",
                    roles      : "admin",
                    match      : "url"
                }
            ]
        }
    },
    // Override cborm module settings
    cborm : {
        eventHandling : true,
        autoEvict     : true
    },
    // Override your own module settings
    myModule : {
        apiKey     : getSystemSetting( "MY_MODULE_API_KEY", "" ),
        timeout    : 30
    }
}

Configuration Best Practices

Use getSystemSetting() for all secrets/credentials — never hard-code them
Use environment override methods (development(), staging(), production()) for per-environment settings
Configure environments regex patterns for automatic environment detection by hostname
Set handlersIndexAutoReload = true in development for instant handler discovery
Use moduleSettings to override module defaults instead of editing module code
Configure dedicated logbox appenders per environment (verbose in dev, file-only in production)
Store LogBox categories that match your application package structure for granular logging control

---name: coldbox-configurationdescription: Use this skill when configuring a ColdBox application in ColdBox.cfc, setting up environments, managing module settings, defining datasources, configuring logging with LogBox, setting up caching with CacheBox, or wiring dependencies with WireBox settings.---# ColdBox Configuration## When to Use This SkillUse this skill when configuring a ColdBox application via `config/ColdBox.cfc` — the master application configuration file.## Language Mode ReferenceExamples use **BoxLang (`.bx`)** syntax by default. Adapt for your target language:| Concept | BoxLang (`.bx`) | CFML (`.cfc`) ||---------|-----------------|---------------|| Class declaration | `class [extends="..."] {` | `component [extends="..."] {` || DI annotation | `@inject` above `property name="svc";` | `property name="svc" inject="svc";` || View templates | `.bxm` suffix | `.cfm` / `.cfml` suffix || Tag prefix | `<bx:if>`, `<bx:output>`, `<bx:set>` | `<cfif>`, `<cfoutput>`, `<cfset>` |> **CFML Compat Mode**: With BoxLang + CFML Compat module, `.bx` and `.cfc` files coexist freely. BoxLang-native classes use `class {}` (`.bx` files); CFML-compat classes use `component {}` (`.cfc` files).## Core ConceptsColdBox.cfc contains sections for:- **`coldbox`** — core framework settings- **`environments`** — environment-specific overrides- **`modules`** — module settings per module- **`interceptors`** — registered interceptors- **`logbox`** — LogBox logging configuration- **`cachebox`** — CacheBox cache configuration- **`wirebox`** — WireBox DI configuration## Full ColdBox.cfc Template```boxlangclass ColdBox extends coldbox.system.Coldbox { function configure() { // ============================================= // COLDBOX SETTINGS // ============================================= coldbox = { // Application name appName : "My ColdBox Application", appMapping : "root", // Application reloading reinitPassword : getSystemSetting( "REINIT_PASSWORD", "supersecret" ), reinitKey : "reinit", // Default handler and view defaultHandler : "main", defaultAction : "index", defaultLayout : "Main", defaultView : "main/index", // Request Defaults requestContextDecorator : "", controllerDecorator : "", // Custom interception points customInterceptionPoints : [ "onUserLogin", "onUserLogout", "onOrderPlaced" ], // Exception handler exceptionHandler : "main.onException", // Invalid event handler invalidEventHandler : "main.onInvalidEvent", // Request timeout requestTimeout : 60, // ColdBox settings handlersIndexAutoReload : true, // Development only modulesExternalLocation : [ "modules" ] } // ============================================= // ENVIRONMENT DETECTION // ============================================= environments = { development : "localhost,127.0.0.1,^local", staging : "staging.example.com", production : "example.com" } // ============================================= // LAYOUTS // ============================================= layoutSettings = { defaultLayout : "Main", defaultView : "main/index" } // ============================================= // MODULES // ============================================= moduleSettings = { // CBSecurity settings cbsecurity : { userService : "UserService", jwtSettings : { secretKey : getSystemSetting( "JWT_SECRET", generateSecretKey( "AES", 256 ) ), expiration : 60 } }, // CBAuth settings cbauth : { userServiceClass : "UserService" }, // CBI18N settings cbi18n : { defaultLocale : "en_US", resourceBundles : { main : "#appMapping#/includes/i18n/main" } } } // ============================================= // INTERCEPTORS // ============================================= interceptors = [ { class : "#appMapping#.interceptors.AppInterceptor", name : "AppInterceptor" } ] // ============================================= // LOGBOX // ============================================= logbox = { // Appenders appenders : { // Console appender (development) console : { class : "coldbox.system.logging.appenders.ConsoleAppender", levelMin : "DEBUG", levelMax : "FATAL" }, // Rolling file appender rolling : { class : "coldbox.system.logging.appenders.RollingFileAppender", levelMin : "WARN", levelMax : "FATAL", properties : { filePath : "#getDirectoryFromPath( getBaseTemplatePath() )#logs", fileName : "app", fileMaxSize : 5000, fileMaxArchives : 2 } } }, // Root logger root : { levelMin : "WARN", levelMax : "FATAL", appenders : "rolling" }, // Category loggers categories : { // App debug "root" : { levelMin : "INFO", levelMax : "DEBUG", appenders : "console" } } } // ============================================= // CACHEBOX // ============================================= cachebox = { // Configuration file configFile : "#appMapping#.config.CacheBox" } // ============================================= // WIREBOX // ============================================= wirebox = { enabled : true, singletonReload : true, binder : "#appMapping#.config.WireBox" } } // ============================================= // ENVIRONMENT-SPECIFIC OVERRIDES // ============================================= function development() { coldbox.handlersIndexAutoReload = true coldbox.reinitPassword = "" coldbox.customErrorTemplate = "/coldbox/system/exceptions/debugPanel.cfm" } function staging() { coldbox.customErrorTemplate = "/coldbox/system/exceptions/customError.cfm" } function production() { coldbox.handlersIndexAutoReload = false coldbox.reinitPassword = getSystemSetting( "REINIT_PASSWORD", "changeme" ) coldbox.customErrorTemplate = "/coldbox/system/exceptions/customError.cfm" }}```**CFML (`.cfc`):**```cfmlcomponent extends="coldbox.system.Coldbox" { function configure() { // ============================================= // COLDBOX SETTINGS // ============================================= coldbox = { // Application name appName : "My ColdBox Application", appMapping : "root", // Application reloading reinitPassword : getSystemSetting( "REINIT_PASSWORD", "supersecret" ), reinitKey : "reinit", // Default handler and view defaultHandler : "main", defaultAction : "index", defaultLayout : "Main", defaultView : "main/index", // Request Defaults requestContextDecorator : "", controllerDecorator : "", // Custom interception points customInterceptionPoints : [ "onUserLogin", "onUserLogout", "onOrderPlaced" ], // Exception handler exceptionHandler : "main.onException", // Invalid event handler invalidEventHandler : "main.onInvalidEvent", // Request timeout requestTimeout : 60, // ColdBox settings handlersIndexAutoReload : true, // Development only modulesExternalLocation : [ "modules" ] } // ============================================= // ENVIRONMENT DETECTION // ============================================= environments = { development : "localhost,127.0.0.1,^local", staging : "staging.example.com", production : "example.com" } // ============================================= // LAYOUTS // ============================================= layoutSettings = { defaultLayout : "Main", defaultView : "main/index" } // ============================================= // MODULES // ============================================= moduleSettings = { // CBSecurity settings cbsecurity : { userService : "UserService", jwtSettings : { secretKey : getSystemSetting( "JWT_SECRET", generateSecretKey( "AES", 256 ) ), expiration : 60 } }, // CBAuth settings cbauth : { userServiceClass : "UserService" }, // CBI18N settings cbi18n : { defaultLocale : "en_US", resourceBundles : { main : "#appMapping#/includes/i18n/main" } } } // ============================================= // INTERCEPTORS // ============================================= interceptors = [ { class : "#appMapping#.interceptors.AppInterceptor", name : "AppInterceptor" } ] // ============================================= // LOGBOX // ============================================= logbox = { // Appenders appenders : { // Console appender (development) console : { class : "coldbox.system.logging.appenders.ConsoleAppender", levelMin : "DEBUG", levelMax : "FATAL" }, // Rolling file appender rolling : { class : "coldbox.system.logging.appenders.RollingFileAppender", levelMin : "WARN", levelMax : "FATAL", properties : { filePath : "#getDirectoryFromPath( getBaseTemplatePath() )#logs", fileName : "app", fileMaxSize : 5000, fileMaxArchives : 2 } } }, // Root logger root : { levelMin : "WARN", levelMax : "FATAL", appenders : "rolling" }, // Category loggers categories : { // App debug "root" : { levelMin : "INFO", levelMax : "DEBUG", appenders : "console" } } } // ============================================= // CACHEBOX // ============================================= cachebox = { // Configuration file configFile : "#appMapping#.config.CacheBox" } // ============================================= // WIREBOX // ============================================= wirebox = { enabled : true, singletonReload : true, binder : "#appMapping#.config.WireBox" } } // ============================================= // ENVIRONMENT-SPECIFIC OVERRIDES // ============================================= function development() { coldbox.handlersIndexAutoReload = true coldbox.reinitPassword = "" coldbox.customErrorTemplate = "/coldbox/system/exceptions/debugPanel.cfm" } function staging() { coldbox.customErrorTemplate = "/coldbox/system/exceptions/customError.cfm" } function production() { coldbox.handlersIndexAutoReload = false coldbox.reinitPassword = getSystemSetting( "REINIT_PASSWORD", "changeme" ) coldbox.customErrorTemplate = "/coldbox/system/exceptions/customError.cfm" }}```## Environment Variables Pattern```boxlang// Using CFML/BoxLang environment variable helperfunction configure() { vars.datasource = getSystemSetting( "DB_DSN", "myapp" ) coldbox = { appName : getSystemSetting( "APP_NAME", "My App" ), reinitPassword : getSystemSetting( "REINIT_PASSWORD", "" ) }}```## Module Settings```boxlang// Override any module setting from ColdBox.cfcmoduleSettings = { // Override cbsecurity module settings cbsecurity : { firewall : { rules : [ { secureList : "admin", roles : "admin", match : "url" } ] } }, // Override cborm module settings cborm : { eventHandling : true, autoEvict : true }, // Override your own module settings myModule : { apiKey : getSystemSetting( "MY_MODULE_API_KEY", "" ), timeout : 30 }}```## Configuration Best Practices- Use `getSystemSetting()` for all secrets/credentials — never hard-code them- Use environment override methods (`development()`, `staging()`, `production()`) for per-environment settings- Configure `environments` regex patterns for automatic environment detection by hostname- Set `handlersIndexAutoReload = true` in development for instant handler discovery- Use `moduleSettings` to override module defaults instead of editing module code- Configure dedicated `logbox` appenders per environment (verbose in dev, file-only in production)- Store LogBox categories that match your application package structure for granular logging control

ColdBox/skills/tree/main/coldbox/configuration commit 5b66a453e7

Frequently asked questions

npx skillmds@latest add coldbox/coldbox-configuration