coldbox-app-layouts

App Layouts

When to Use This Skill

Use this skill when:

• Creating a new ColdBox application from scratch and choosing a project structure
• Deciding between the flat, boxlang, and modern application templates
• Scaffolding via box coldbox create app skeleton=<name>
• Understanding directory conventions for an existing app
• Migrating from one layout to another

Language & Engine Compatibility

Layout	CFML (Adobe CF / Lucee)	BoxLang
flat	Yes	Yes
boxlang	No	Yes only
modern	Yes	Yes

Default: The ColdBox CLI (coldbox create app) defaults to the boxlang skeleton. Pass --cfml or skeleton=flat / skeleton=modern to use another layout.

Flat Layout

Template repo: https://github.com/coldbox-templates/flat

The flat layout places all application code directly in the web root. It is the traditional ColdBox structure and the widest-compatibility choice — works with Adobe ColdFusion, Lucee, and BoxLang.

Flat: Directory Map

/
├── Application.cfc             # App bootstrap
├── index.cfm                   # Front controller
├── box.json                    # CommandBox package descriptor
├── server.json                 # Server configuration
├── pom.xml                     # Maven Java dependencies (optional)
│
├── config/
│   ├── ColdBox.cfc             # Framework settings
│   ├── Router.cfc              # URL routing
│   └── WireBox.cfc             # DI bindings (optional)
│
├── handlers/                   # Event handlers (controllers)
├── models/                     # Services, beans, business logic
├── views/                      # View templates
├── layouts/                    # Layout wrappers
├── interceptors/               # Event interceptors
├── modules_app/                # Internal HMVC modules
│
├── includes/                   # Public assets (CSS, JS, images)
│   ├── css/
│   ├── js/
│   └── images/
│
├── tests/
│   ├── Application.cfc
│   ├── runner.cfm
│   └── specs/
│       ├── integration/
│       └── unit/
│
└── lib/                        # Framework libraries (managed by CommandBox)
    ├── coldbox/
    └── testbox/

Flat: Best For

• Rapid prototyping and quick-start projects
• Learning ColdBox — the structure is immediately visible
• Traditional shared hosting environments
• Teams familiar with standard CFML application structures
• Internal tools that do not require strict code/web-root separation

Flat: Caveats

• All application code (handlers, models, config) lives under the web root and is theoretically directly accessible
• Modules with UI assets require no special alias configuration since everything is in the same root
• Not recommended for security-critical production deployments without additional server-level restrictions

Flat: Scaffold Command

box coldbox create app name=myApp skeleton=flat

---

BoxLang Layout

Template repo: https://github.com/coldbox-templates/boxlang

The BoxLang layout is the default modern architecture for BoxLang-native applications. It uses the same /app + /public separation as the Modern layout but adds BoxLang-specific assets: .bx class files, a runtime/ configuration directory, a Build.bx build script, Vite frontend tooling, and native BoxLang mappings pre-configured in runtime/config/boxlang.json.

BoxLang: Directory Map

/
├── box.json                    # CommandBox package descriptor
├── server.json                 # CommandBox server config (webroot = public/)
├── pom.xml                     # Maven Java deps (optional)
├── Build.bx                    # BoxLang build + distribution script
│
├── app/                        # Application code (NOT web-accessible)
│   ├── config/
│   │   ├── ColdBox.bx          # Framework settings
│   │   ├── Router.bx           # URL routing
│   │   ├── WireBox.bx          # DI bindings (optional)
│   │   ├── CacheBox.bx         # Caching config (optional)
│   │   └── Scheduler.bx        # Task scheduling (optional)
│   ├── handlers/               # Event handlers
│   ├── helpers/                # Application helpers (optional)
│   ├── interceptors/           # Event interceptors
│   ├── layouts/                # View layouts
│   ├── logs/                   # App logs (optional)
│   ├── models/                 # Business logic
│   ├── modules/                # App-specific modules (optional)
│   └── views/                  # View templates (.bxm)
│
├── public/                     # Web root (CommandBox points here)
│   ├── Application.bx          # Web-facing bootstrap
│   ├── index.bxm               # Front controller
│   ├── favicon.ico
│   ├── robots.txt
│   └── includes/               # Static assets
│
├── lib/                        # Dependencies (managed by CommandBox)
│   ├── coldbox/
│   ├── testbox/
│   ├── modules/                # ColdBox modules
│   └── java/                   # Java JARs (managed by Maven)
│
├── resources/                  # Non-web resources
│   ├── migrations/             # Database migrations (cbmigrations)
│   ├── docker/                 # Docker configuration (optional)
│   ├── seeders/                # Database seeders
│   ├── swagger/                # API docs (cbswagger)
│   └── assets/                 # Vite source assets (if using Vite)
│       ├── css/
│       └── js/
│
├── runtime/                    # BoxLang runtime overrides
│   ├── boxlang.json            # Custom BoxLang configuration
│   ├── global/
│   │   ├── classes/
│   │   └── components/
│   └── logs/
│
└── tests/
    ├── Application.bx
    ├── runner.cfm
    └── specs/
        └── integration/

BoxLang: Best For

• BoxLang-native applications where you want idiomatic .bx classes throughout
• Projects using the BoxLang OS runtime for CLI/script use alongside web serving
• Applications leveraging Vite for modern frontend asset pipelines (Vue 3, Tailwind)
• Production BoxLang deployments with compiled bytecode distribution via Build.bx
• Teams fully committed to the BoxLang ecosystem

BoxLang: Caveats

• BoxLang only — does not support Adobe ColdFusion or Lucee
• Requires BoxLang OS runtime (1.6+) in addition to CommandBox for the build script
• Module web UI assets require server.json aliases (same as Modern)
• Test components must include appMapping="/app"
• The runtime/ directory is BoxLang-specific and does not exist in Flat or Modern

BoxLang: Scaffold Command

# Default — this is what `box coldbox create app` uses
box coldbox create app name=myApp

# Explicit
box coldbox create app name=myApp skeleton=boxlang

# With optional features
box coldbox create app name=myApp skeleton=boxlang --vite --docker --migrations

BoxLang: Testing Baseline

// tests/specs/integration/MainSpec.bx
class extends="coldbox.system.testing.BaseTestCase" appMapping="/app" {

    function beforeAll() {
        super.beforeAll()
    }

    function run(){
        describe( "Main Handler", function(){
            beforeEach( function( currentSpec ){
                setup()
            })

            it( "can render the homepage", function(){
                var event = this.get( "main.index" )
                expect( event.getRenderedContent() ).notToBeEmpty()
            })
        })
    }
}

---

Modern Layout

Template repo: https://github.com/coldbox-templates/modern

The Modern layout implements a security-first architecture by separating application code from the web root. It is compatible with both Adobe ColdFusion (2021+) and BoxLang. Unlike the BoxLang layout, it uses .cfc files and traditional CFML tag syntax throughout; BoxLang .bx files may be used when running on BoxLang with CFML compat mode.

Note: Lucee is not supported by this template.

Modern: Directory Map

/
├── box.json                    # CommandBox package descriptor
├── server.json                 # CommandBox server config (webroot = public/)
├── pom.xml                     # Maven Java deps (optional)
│
├── app/                        # Application code (NOT web-accessible)
│   ├── Application.cfc         # Contains only `abort;` to block direct access
│   ├── config/
│   │   ├── ColdBox.cfc         # Framework settings
│   │   ├── Router.cfc          # URL routing
│   │   ├── WireBox.cfc         # DI bindings (optional)
│   │   └── CacheBox.cfc        # Caching config (optional)
│   ├── handlers/               # Event handlers
│   ├── helpers/                # Application helpers (optional)
│   ├── interceptors/           # Event interceptors
│   ├── layouts/                # View layouts
│   ├── logs/                   # App logs
│   ├── models/                 # Business logic
│   └── views/                  # View templates (.cfm)
│
├── public/                     # Web root (CommandBox points here)
│   ├── Application.cfc         # Bootstrap that maps to /app
│   ├── index.cfm               # Front controller
│   ├── favicon.ico
│   ├── robots.txt
│   └── includes/               # Static assets (CSS, JS, images)
│
├── lib/                        # Dependencies (managed by CommandBox)
│   ├── coldbox/
│   ├── testbox/
│   ├── modules/                # ColdBox modules
│   └── java/                   # Java JARs (managed by Maven)
│
├── resources/                  # Non-web resources
│   ├── database/               # Migrations and seeders
│   └── apidocs/                # API documentation
│
└── tests/
    ├── Application.cfc
    ├── runner.cfm
    ├── index.cfm
    └── specs/
        └── integration/

Modern: Best For

• Production and enterprise applications requiring code/web-root separation
• Mixed CFML + BoxLang teams where Adobe CF 2021+ or BoxLang is the target engine
• Security-conscious deployments where application logic must not be directly web-accessible
• Environments where you cannot configure server-level URL rewriting to block access to application directories

Modern: Caveats

• Module web UI assets (e.g., cbdebugger, cbswagger) require server.json aliases since lib/ is outside the web root
• Test components must include appMapping="/app" in BaseTestCase
• Direct HTTP access to /app/ returns 404 by design — this is intentional
• app/Application.cfc only contains abort; as a security barrier

Modern: Scaffold Command

box coldbox create app name=myApp skeleton=modern

Critical server.json Aliases

{
    "web": {
        "webroot": "public",
        "rewrites": { "enable": true },
        "aliases": {
            "/coldbox/system/exceptions": "./lib/coldbox/system/exceptions/",
            "/tests": "./tests/"
        }
    }
}

Add an alias for every module that exposes web assets:

"/cbdebugger": "./lib/modules/cbdebugger"

Modern: Testing Baseline

// tests/specs/integration/MainSpec.cfc
component extends="coldbox.system.testing.BaseTestCase" appMapping="/app" {

    function beforeAll(){
        super.beforeAll()
    }

    function run(){
        describe( "Main Handler", function(){
            beforeEach( function( currentSpec ){
                setup()
            })

            it( "can render the homepage", function(){
                var event = this.get( "main.index" )
                expect( event.getRenderedContent() ).notToBeEmpty()
            })
        })
    }
}

---

Choosing the Right Layout

Scenario	Recommended Layout
Learning ColdBox or rapid prototyping	flat
Simple internal tool on traditional hosting	flat
BoxLang-native app, CLI + web, or Vite frontend	boxlang
Full BoxLang ecosystem (compiled builds, BoxLang OS)	boxlang
Production Adobe CF or mixed CF/BoxLang team	modern
Enterprise security-first deployment	modern
Multi-engine team (Lucee included)	flat (only layout supporting Lucee)

Decision Flowchart

Are you using BoxLang exclusively?
├── Yes → Do you need Vite, Build.bx, or BoxLang OS runtime?
│         ├── Yes → boxlang
│         └── No  → boxlang (still the default) or modern
└── No  → Does security or deployment require code outside the web root?
          ├── Yes → modern
          └── No  → flat

Migrating Between Layouts

Flat to Modern or BoxLang

1. Move handlers/, models/, views/, layouts/, interceptors/, config/ into app/
2. Create public/ with Application.cfc (or .bx) that sets COLDBOX_APP_ROOT_PATH and COLDBOX_APP_MAPPING="/app"
3. Move index.cfm (or index.bxm) and static assets to public/
4. Update server.json to set webroot = "public" and add any module aliases
5. Update all test components to include appMapping="/app"

Modern to BoxLang

1. Rename .cfc files to .bx and replace component with class
2. Rename .cfm/.cfml view/layout files to .bxm
3. Rename config files (ColdBox.cfc → ColdBox.bx, Router.cfc → Router.bx, etc.)
4. Add a runtime/ directory with boxlang.json for BoxLang mappings
5. Add Build.bx if you need compiled distribution builds