Directory Structure
Understanding the Wheels directory structure is essential whether you're building applications or contributing to the framework itself.
Two Structures for Different Workflows
Wheels uses different directory layouts depending on your role:
Application Development: A streamlined structure optimized for building applications, available through ForgeBox or the CLI.
Framework Development: A comprehensive monorepo structure that includes development tools, tests, and documentation for framework contributors.
Both structures serve specific purposes, and understanding each will help you work more effectively with Wheels.
Application Development Structure
When you create a new Wheels application using wheels new
or download from ForgeBox, you'll work with this focused project structure:
app/
controllers/
Controller.cfc
events/
global/
migrator/
migrations/
models/
Model.cfc
plugins/
views/
config/
public/
files/
images/
javascripts/
stylesheets/
miscellaneous/
Application.cfc
urlrewrite.xml
Application.cfc
index.cfm
tests/
TestBox/
vendor
Core Application Directories
app/controllers/ - Contains your controller files with a base Controller.cfc
file already present. Place shared controller methods in Controller.cfc
since all controllers inherit from this base class.
app/models/ - Houses your model files, typically one per database table. The existing Model.cfc
file serves as the base class for all models and should contain shared model functionality.
app/views/ - Stores your view templates, organized by controller (e.g., views for the Users
controller go in app/views/users/
). This is where you prepare content for your users.
app/events/ - Contains event handlers that respond to ColdFusion application events, providing a cleaner alternative to placing code directly in Application.cfc
.
app/global/ - Holds globally accessible functions available throughout your application.
app/plugins/ - Contains downloaded Wheels plugins that extend your application's functionality.
Database Management - Use the migration system (wheels db migrate
) rather than manual SQL scripts for database schema changes.
Package Management - Use CommandBox and the box.json
file to manage dependencies. The vendor/
directory contains installed packages and should be excluded from version control.
Local Development - Configure your development environment using server.json
for server settings and .env
for environment variables. Never commit sensitive data in .env
files to version control.
Configuration and Assets
config/ - All configuration changes should be made here. Set environments, routes, and other application settings. Individual setting files in subdirectories can override main configuration.
public/files/ - Files intended for delivery to users via the sendFile()
function should be placed here. Also serves as general file storage.
public/images/ - Recommended location for image assets. While not required, Wheels functions involving images assume this conventional location.
public/javascripts/ - Recommended location for JavaScript files.
public/stylesheets/ - Recommended location for CSS files.
public/miscellaneous/ - Special directory for code that must run completely outside the framework. Contains an empty Application.cfc
that prevents Wheels involvement. Ideal for Flash AMF binding or <cfajaxproxy>
connections to CFCs.
System Files and Testing
app/migrator/migrations - Database migration CFC files.
tests/TestBox/ - Location for your application's unit tests.
public/urlrewrite.xml - Required for Tomcat/Tuckey or CommandBox URL rewriting.
public/Application.cfc and public/index.cfm - Framework bootstrap files. Do not modify these files.
Framework Development Structure
Contributors working on the Wheels framework itself will encounter this comprehensive repository structure:
cli/
core/
src/
wheels/
design_docs/
docs/
examples/
templates/
base/
src/
app/
config/
public/
tests/
vendor/
.env
box.json
server.json
test-artifacts/
tests/
tools/
.cfformat.json
.editorconfig
CFConfig.json
CHANGELOG.md
compose.yml
Framework Development Components
cli/ - Source code for command-line interface tools including generators and database migration utilities.
core/src/wheels/ - The core Wheels framework code. This is the actual framework that gets distributed. When new versions are released, this directory often contains all necessary updates.
design_docs/ - Architecture documentation, design decisions, and planning materials explaining the framework's structural choices.
docs/ - Official documentation in Markdown format, synchronized with the public website at wheels.dev.
examples/ - Sample applications demonstrating various Wheels features, useful for testing framework changes in realistic scenarios.
/ - The exact application template structure that developers receive when creating new projects. This mirrors the application development structure described above and includes essential configuration files like box.json
, server.json
, and .env
.
vendor/ - Third-party dependencies and packages used by the framework development environment. Contains libraries managed through CommandBox/ForgeBox package management.
test-artifacts/ - Files generated during test suite execution, typically excluded from version control.
tests/ - Complete TestBox test suite for framework validation and regression testing.
tools/ - Build scripts, Docker configurations, and development utilities for maintaining the framework.
Configuration files (.cfformat.json
, .editorconfig
, CFConfig.json
) maintain consistent development standards across contributor environments.
Key Directory Relationships
Application Context
When working on applications, your primary focus areas are:
Configuration:
config/
directory for all settingsApplication Logic:
app/controllers/
,app/models/
,app/migrator/migrations
,app/views/
, andapp/events/
Static Assets:
public/files/
,public/images/
,public/javascripts/
, andpublic/stylesheets/
Extensions:
app/plugins/
for third-party functionality
Framework Context
The /
folder in the framework repository becomes the root directory of every new Wheels application. When contributing to the framework:
Work primarily in
core/src/wheels/
for framework codeUpdate
docs/
for documentation changesTest changes using applications in
/
orexamples/
Use
tests/
for framework testing
Directory Customization
You can add additional directories to your application structure. When doing so:
Include a blank
Application.cfc
file in custom directories to prevent Wheels from processing requests in those locationsFollow the established naming conventions for consistency
Consider whether new directories belong in
public/
(web-accessible) orapp/
(application logic)
Guidelines for Contributors
Environment Setup - Use the provided compose.yml
file to test changes across multiple CFML engines, ensuring broad compatibility.
Testing Requirements - Execute the complete test suite located in /tests
before submitting pull requests to prevent regressions.
Code Standards - Follow the formatting rules defined in .cfformat.json
. Most development environments can automatically apply these standards.
Documentation Updates - Update relevant documentation in /docs
when adding features or modifying existing behavior.
CLI Development - When working on command-line tools, ensure corresponding documentation updates in /docs/command-line-tools
.
Guidelines for Application Developers
Configuration First - Begin development by setting up routes, environments, and database connections in the config/
directory.
MVC Architecture - Organize code according to the Model-View-Controller pattern that the directory structure supports:
Controllers handle requests and coordinate between models and views
Models manage data and business logic
Views present information to users
Asset Organization - Use the conventional public/
subdirectories for different asset types. This ensures Wheels functions work as expected and maintains project organization.
Plugin Integration - Evaluate existing plugins in app/plugins/
before developing custom solutions.
Database Management - Use the migration system (wheels db migrate
) rather than manual SQL scripts for database schema changes.
Package Management - Use CommandBox and the box.json
file to manage dependencies. The vendor/
directory contains installed packages and should be excluded from version control.
Local Development - Configure your development environment using server.json
for server settings and .env
for environment variables. Never commit sensitive data in .env
files to version control.
Testing Strategy - Implement unit tests in tests/TestBox/
to ensure application reliability.
This directory structure reflects years of framework development and community feedback. Each directory serves a specific purpose that supports either application development or framework contribution. The clear separation between public assets, application logic, and configuration ensures maintainable and scalable Wheels applications.
Last updated
Was this helpful?