Wheels

Wheels provides fast application development, a great organization system for your code, and is just plain fun to use.

One of our biggest goals is for you to be able to get up and running with Wheels quickly. We want for you to be able to learn it as rapidly as it is to write applications with it.

Getting Started

Quick Start

Install the Wheels CLI (Homebrew on macOS and Linux):

brew tap wheels-dev/wheels
brew install wheels
wheels new myapp

Homebrew 5.1+ asks you to trust third-party taps on first use — run brew trust wheels-dev/wheels once if prompted.

The CLI is powered by LuCLI — it ships with Lucee and depends only on Java 21, so no CommandBox install is required.

Learning Wheels

In this Beginner Tutorial: Hello World, we'll be writing a simple application to make sure we have Wheels installed properly and that everything is working as it should. Along the way, you'll get to know some basics about how applications built on top of Wheels work.

System Requirements

CFML Engines:

• Adobe ColdFusion: 2018, 2021, 2023, 2025
• Lucee: 5.x, 6.x, 7.x
• BoxLang: 1.x

Supported Databases:

• SQLite (new in 3.0!)
• Oracle (new in 3.0!)
• Microsoft SQL Server
• PostgreSQL
• MySQL
• H2

Note: Adobe ColdFusion 2016 is no longer supported as of Wheels 3.0.

Project Structure

Wheels 3.0 introduces a clean, modern project structure:

your-app/
├── app/
│   ├── controllers/
│   ├── models/
│   ├── views/
│   └── ...
├── config/
├── public/
├── tests/
├── vendor/
│   └── wheels/
└── ...

Monorepo Structure

This repository contains the complete Wheels ecosystem in a monorepo structure. All components are developed together but distributed as separate ForgeBox packages.

wheels-monorepo/
├── cli/                    # Wheels CLI (LuCLI-powered)
│   └── lucli/              # LuCLI module entry point
├── core/                   # Framework Core
│   └── src/wheels/         # Published as 'wheels-core'
├── templates/              # Application Templates
│   └── base/src/           # Starting structure for new apps
├── docs/                   # Documentation
│   └── src/                # Published to wheels.dev/guides
├── examples/               # Example applications
├── tools/
│   └── build/scripts/      # Build and packaging scripts
└── tests/                  # Framework test suite

Key Components:

• CLI (wheels): Development tools and generators, distributed via Homebrew, Scoop and apt/yum packages that bundle LuCLI (the Wheels build, wheels-dev/LuCLI, pinned in tools/lucli.json)
• Core (wheels-core): Framework runtime installed in /vendor/wheels
• Base Template (wheels-base-template): Starting structure used by the CLI for new applications
• Documentation: Comprehensive guides published to wheels.dev/guides
• Build System: Automated packaging and release distribution

Package Flow: the CLI stages the base template when you run wheels new myapp, which pulls in the core framework as a dependency. Documentation is automatically published to wheels.dev/guides. All components are versioned together and released through Homebrew, Chocolatey, and GitHub releases.

For detailed monorepo documentation, see MONOREPO.md which includes:

• Complete directory structure breakdown
• Component relationships and dependency graphs
• Development workflow and testing procedures
• Build and distribution pipeline details

Contributing

We encourage you to contribute to Wheels! Whether you're fixing bugs, adding features, improving documentation, or helping with discussions, your contributions make Wheels better for everyone.

Two Ways to Contribute:

1. Developer Applications - Built using wheels new command for application development
2. Framework Core - The wheels-dev/wheels monorepo for core framework contributions

Please check out our Contributing Guide for detailed guidelines on how to get started. We've made the contribution process as smooth as possible with Docker support, comprehensive testing setup, and clear documentation.

Running Tests

Important: Before running tests, make sure that all debugging is turned OFF. This could add a considerable amount of time for the tests to complete and may cause your engine to become unresponsive.

Test Database Setup

1. Create a database on a supported database server named wheelstestdb
   • Supported servers: SQLite, Oracle, Microsoft SQL Server, PostgreSQL, MySQL, H2
2. Create a datasource in your CFML engine's administrator named wheelstestdb pointing to the wheelstestdb database
3. Important: Make sure to give it CLOB and BLOB support
4. Open your browser to the Wheels Welcome Page
5. In the navigation menu, click the Tests > core Tests

Docker Testing

1. Create a database on a supported database server named wheelstestdb. At this time the supported database servers are H2, Microsoft SQL Server, PostgreSQL, MySQL, Oracle and SQLite.
2. Create a datasource in your CFML engine's administrator named wheelstestdb pointing to the wheelstestdb database and make sure to give it CLOB and BLOB support.
3. Open your browser to the Wheels Welcome Page.
4. In the gray debug area at the bottom of the page, click the Run Tests link next to the version number on the Framework line.

For multi-engine testing, use our Docker setup

Reporting Issues

Please report any errors you encounter on our issue tracker. When reporting, please include:

• Database engine and version
• CFML engine and version
• HTTP server and version
• Steps to reproduce the issue

Getting Help

• Documentation: wheels.dev
• Community: GitHub Discussions
• Issues: GitHub Issues
• Guides: Framework Guides

Supported CFML Engines

Wheels supports the following CFML engines:

• Adobe ColdFusion: 2018, 2021, 2023, 2025
• Lucee: 5.x, 6.x, 7.x
• BoxLang: 1.x

License

Wheels is released under the Apache License Version 2.0.

Our Contributors

Made with contrib.rocks.

---

Wheels 3.0 - Faster, more organized, and just plain fun to use!