Welcome to Wheels

A two-minute orientation before you write any code.

You’ll learn:

• What Wheels is, in one paragraph
• Who these guides are for
• How to find your way around

Note

No prior Wheels experience assumed. Some general programming background helps — you’ve built a web app in something, probably Rails, Laravel, Django, or Express.

What Wheels is

Wheels is a full-stack web framework for CFML. It runs on Lucee (open source), Adobe ColdFusion (commercial), and BoxLang. It gives you an ActiveRecord-style ORM, a request pipeline with middleware, a convention-driven file layout, and a scaffold generator that writes working code from a model name. You spend your time on the interesting parts of your app.

The wheels CLI is the only tool you need. It creates apps, runs migrations, generates scaffolds, starts the dev server, runs tests, and ships your code. Under the hood it wraps a Java-based CFML runtime; you rarely think about that.

Wheels has been shipping since 2005. Version 4.0 is the current line. The framework name is “Wheels” — it was renamed from “CFWheels” at v3.0, so don’t be confused by old blog posts.

Who these guides are for

Primary audience: developers new to Wheels. You may also be new to CFML. Both are fine.

You’re probably in one of these camps:

• You’ve built with Rails, Laravel, or Django and want to know what Wheels looks like. Start with Why Wheels? for a head-to-head comparison, then follow the tutorial.
• You inherited a CFML codebase and want to modernize it. Read Why Wheels? to see where 4.0 sits relative to older CFML frameworks, then jump to Upgrading.
• You know Wheels 3.x and want to see what changed. The tutorial shows off 4.0-native features (Turbo via Hotwire, built-in auth, query builder, enums, seeds, middleware). After that, Upgrading to 4.0 has the migration checklist.

These guides are not for framework contributors (see CONTRIBUTING.md in the repo) and not a method-by-method API reference (see api.wheels.dev).

How these guides are organized

The structure follows Diátaxis: four kinds of documentation, each with a different job. Knowing the kind helps you pick the right page.

• Start Here (this section) — orientation and the opening tutorial. The fastest way in.
• Core Concepts — explanations. How Wheels thinks. Read these when something feels surprising.
• The Basics — task-oriented how-tos for everyday features: routing, forms, validation, models, associations, migrations.
• Digging Deeper — task-oriented how-tos for the harder stuff: authentication, background jobs, caching, multi-tenancy, packages.
• Testing — everything about writing and running tests, including browser tests.
• Deployment & Operations — getting your app to production and keeping it there.
• CLI Reference — every wheels command, what it does, what flags it takes.
• Contributing & Project — how to contribute code, docs, or bug reports.
• Upgrading — migrating between Wheels versions.
• Glossary — every Wheels term defined in one place.

A page’s type: tag in its frontmatter tells you which kind it is. Reference pages are dry on purpose — tables and lists, no narrative. Tutorials hand-hold. How-tos assume you know what you’re trying to do and just need the steps.

The fastest path in

Three ways to start, in order of time commitment:

Install the CLI Five minutes. macOS, Windows, or Linux.

Your First 15 Minutes Zero to a running page. No concepts, just commands.

Build a Blog (tutorial) Three and a half hours. Models, scaffolds, auth, Turbo, tests. The real introduction.

See also

• Why Wheels? — head-to-head with Rails, Laravel, and Django
• Core Concepts — the mental model
• CLI Reference — every wheels command