wheels deps

Manage application dependencies using box.json.

Synopsis

wheels deps <action> [name] [options]

Description

The wheels deps command provides a streamlined interface for managing your Wheels application's dependencies through box.json. It integrates with CommandBox's package management system while providing Wheels-specific conveniences.

Arguments

Argument	Description	Default
action	Required - Action to perform: list, install, update, remove, report	None
name	Package name (required for install/update/remove actions)	None
version	Specific version to install (optional, for install action only)	Latest version

Options

Option	Description	Default
--dev	Install as development dependency (install action only)	false

Actions

List

Display all dependencies from box.json with their installation status.

wheels deps list

Output shows:

• Package name

• Version specification

• Type (Production/Development)

• Installation status

Example output:

Dependencies:
  wheels-core @ ^3.0.0 (Production) - Installed
  wirebox @ ^7 (Production) - Installed
  testbox @ ^5 (Production) - Installed

Dev Dependencies:
  commandbox-dotenv @ * (Development) - Not Installed
  commandbox-cfformat @ * (Development) - Installed

Install

Install a new dependency and add it to box.json.

wheels deps install <name>
wheels deps install <name> <version>
wheels deps install <name> --dev

Examples:

# Install latest version as production dependency
wheels deps install cbvalidation

# Install specific version
wheels deps install cbvalidation 3.0.0

# Install as development dependency
wheels deps install testbox --dev

Update

Update an existing dependency to the latest version allowed by its version specification.

wheels deps update <name>

Example:

wheels deps update wirebox

The command will:

• Check if the dependency exists in box.json

• Determine if it's a production or dev dependency

• Update to the latest compatible version

• Show version change information

Remove

Remove a dependency from both box.json and the file system.

wheels deps remove <name>

Example:

wheels deps remove oldpackage

Note: Remove action will ask for confirmation before proceeding.

Report

Generate a comprehensive dependency report with outdated package check.

wheels deps report

The report includes:

• Project information (name, version)

• Wheels version

• CFML engine details

• All dependencies with installation status

• Development dependencies

• Installed modules information

• Outdated package check

• Export to JSON file

Example output:

Dependency Report:

Generated: 2025-06-04 10:05:35
Project: my-wheels-app
Project Version: 1.0.0
Wheels Version: 3.0.0
CFML Engine: Lucee 5.4.6.9

Dependencies:
  wheels-core @ ^3.0.0 - Installed: Yes
  wirebox @ ^7 - Installed: Yes

Dev Dependencies:
  testbox @ ^5 - Installed: Yes

Checking for outdated packages...
All packages are up to date!

Full report exported to: dependency-report-20250604-100535.json

Integration with CommandBox

The wheels deps commands delegate to CommandBox's package management system:

• install uses box install

• update uses box update

• remove uses box uninstall

• report uses box outdated

This ensures compatibility with the broader CFML package ecosystem.

Working with box.json

The command manages two dependency sections in box.json:

Production Dependencies

{
  "dependencies": {
    "wheels-core": "^3.0.0",
    "wirebox": "^7"
  }
}

Development Dependencies

{
  "devDependencies": {
    "testbox": "^5",
    "commandbox-cfformat": "*"
  }
}

Installation Status

The command checks for installed packages in the /modules directory. It handles various package naming conventions:

• Simple names: wirebox

• Namespaced: forgebox:wirebox

• Versioned: [email protected]

Error Handling

Common scenarios:

• No box.json: Prompts to run box init

• Package not found: Shows available dependencies

• Update failures: Shows current and attempted versions

• Network issues: Displays CommandBox error messages

Best Practices

1. Initialize First: Run box init before managing dependencies

2. Use Version Constraints: Specify version ranges for stability

3. Separate Dev Dependencies: Use --dev for test/build tools

4. Regular Updates: Run wheels deps report to check for outdated packages

5. Commit box.json: Always version control your dependency specifications

Notes

• Dependencies are installed to the /modules directory

• The command respects CommandBox's dependency resolution

• Version specifications follow npm-style semver patterns

• Dev dependencies are not installed in production environments

See Also

• box install - CommandBox package installation

• box.json - Package descriptor documentation

• wheels init - Initialize a Wheels application

• wheels plugins - Manage Wheels CLI plugins