Skip to content

cfml-engines.mdx

Latest commit

 

History

History
115 lines (80 loc) · 6.25 KB

cfml-engines.mdx

File metadata and controls

115 lines (80 loc) · 6.25 KB
Raw
title CFML Engines
description Run Wheels on Lucee, Adobe ColdFusion, or BoxLang. The wheels CLI ships with Lucee; the framework runs on all three.
type explanation
sidebar
order
6

import { Aside, Tabs, TabItem, Steps, CardGrid, LinkCard } from '@astrojs/starlight/components';

Wheels is the framework. The framework runs on three CFML engines: Lucee, Adobe ColdFusion, and BoxLang. The wheels CLI is a separate thing — it's a developer convenience that bundles a Lucee runtime so newcomers can brew install wheels and have a working dev server in one step. If you need Adobe CF or BoxLang for development or production, you don't use the wheels CLI's bundled runtime; you use a CommandBox-managed server (or a manual install) and the framework handles the rest.

TL;DR

Engine Use the wheels CLI? Run via CommandBox? Production-supported?
Lucee 6 / 7 Yes — bundled, recommended Yes Yes
Adobe ColdFusion 2023 / 2025 No — install manually Yes — recommended Yes
BoxLang No Yes Yes

The framework's CI matrix (.github/workflows/compat-matrix.yml) runs every release against Lucee 6, Lucee 7, Adobe CF 2023, Adobe CF 2025, and BoxLang on each release. Engine support is hard-gated.

Why the wheels CLI is Lucee-only

The wheels CLI is a thin wrapper around LuCLI — a single-binary CFML launcher that boots Lucee Express on demand. LuCLI doesn't ship Adobe CF or BoxLang runtimes (it's not authorised to redistribute Adobe CF, and the BoxLang launcher is a separate project), so wheels start always boots Lucee.

If you're starting fresh and don't have engine preferences yet, stay on Lucee — it's the path of least resistance and the default the rest of the docs assume.

Running Wheels on Adobe ColdFusion

Two routes, depending on what you already have installed.

Route 1 — CommandBox (recommended)

CommandBox is a CFML server manager from Ortus Solutions. It can boot Adobe CF, Lucee, or BoxLang on demand, downloading the engine on first use. This is the standard path for Adobe CF development on Wheels.

  1. Install CommandBox. macOS: brew install commandbox. Windows: choco install commandbox. Linux: see the CommandBox docs.

  2. Generate a Wheels app with the wheels CLI as usual — the bundled Lucee will be used to scaffold the project, but you can switch engines in the next step:

    wheels new myApp
cd myApp

  3. Boot CommandBox with Adobe CF in the project directory:

    box server start cfengine=adobe@2025 port=8080

    First run downloads the Adobe CF engine (~500 MB). CommandBox writes a server.json you can commit if you want the team to pin the engine version.

  4. Run migrations the way you would on Lucee:

    wheels migrate latest

    The wheels CLI hits the running server's /wheels/cli endpoint, which works the same on every engine.

Route 2 — Manual Adobe ColdFusion install

If you already have Adobe CF installed (e.g. the dev edition from coldfusion.adobe.com), point its web root at your Wheels app's public/ directory and configure the datasource through the CF Administrator. The framework requires no engine-specific setup beyond having a registered datasource.

The `wheels start`, `wheels stop`, `wheels reload`, and `wheels test` commands all assume the Lucee Express bundled with the CLI. On Adobe CF you'll use `box server start/stop/restart` instead, and reload via `?reload=true&password=` directly. Generators (`wheels generate ...`) are pure file-system operations and work the same regardless of engine — with one exception: `wheels generate admin` introspects your database schema through a running server bound to the project, and refuses to run without one.

Running Wheels on BoxLang

BoxLang is Ortus's modern CFML alternative. CommandBox supports BoxLang as a server engine just like it does Adobe CF.

wheels new myApp
cd myApp
box server start cfengine=boxlang@latest port=8080
The `wheels start`, `wheels stop`, `wheels reload`, and `wheels test` commands all assume the Lucee Express bundled with the CLI — they do not interact with BoxLang. BoxLang developers manage their server through CommandBox (`box server start/stop/restart`) and reload via `?reload=true&password=` directly. Generators (`wheels generate ...`) are pure file-system operations and work the same regardless of engine — with one exception: `wheels generate admin` introspects your database schema through a running server bound to the project, and refuses to run without one.

Wheels' BoxLang compatibility is verified per release in the same CI matrix as Lucee and Adobe CF. Cross-engine gotchas worth knowing about live in .ai/wheels/cross-engine-compatibility.md — most are about minor differences in struct/array semantics under closures.

Pick an engine

  • You're new to Wheels and want the easiest path: Lucee, with the bundled wheels CLI. Skip the rest of this page.
  • Your team standardised on Adobe CF: CommandBox + Adobe CF. Skip the bundled CLI's start/stop commands; use box server instead.
  • You want a modern, performant CFML runtime and don't have legacy Adobe scripts to support: BoxLang via CommandBox.
  • You're shipping to a production server you don't control: the framework runs on whatever engine that server uses; the wheels CLI doesn't ship to production.

Related