In the CFML world, there are no global conventions for where to install things to nor where to store dependencies. Therefore, CommandBox for the most part will just stick packages in the root of your site unless you tell it otherwise. It may not be pretty, but it's as good as stock CFML apps can get. That means a lot of the cool things other package managers like NPM can do simply won't be available to you.
If you're using the ColdBox MVC Platform, congratulations! You just unlocked advanced mode! ColdBox uses conventions that tells you where to put stuff, and most importantly it has modularity as a first class citizen. Not only that, but modules can be nested infinitely to nicely encapsulate dependencies and WireBox will automatically find and register each module's models for your application to use.
Modules are basically smart packages and when CommandBox installs or uninstalls modules it will behave a bit differently to take advantage of the functionality only available to the CFML world via the ColdBox Platform.
When installing a module, it will be placed in the modules/ directory. That means the cbvalidation module will install here:
The cbvalidation module has dependencies of its own but it is an island unto itself and will encapsulate these. Therefore the cbi18n module will be installed in a modules/ folder inside cbvalidation.
You'll be able to see a nice representation of this when you use the list command.
What this opens the door for is more than one module to depend on different versions of the same second module. Both can be installed and nested under the respective parent. In the near future, WireBox will be smart enough to present these nested modules only to their parents so they are fully encapsulated.
The idea is that a module can "see" and use another module installed at the same level or higher in the hierarchy, but not lower. That makes dependencies a bit of a black box to their parents. This also allows us to bypass some redundancy. For instance, when installing a module, if a satisfying version of that module already exists at a higher level, we skip the installation. Consider this example:
We know that cbvalidation requires cbi18n, but since it is already installed in the root modules folder, we won't install it again under cbvalidation.
The last way modules are better than sliced papusas is in how they uninstall. We talked about how non-modules install-- just littered in the web root in a jumble of dependencies. When uninstalling a non-module package, CommandBox will recursively go through the dependencies and remove them as well. However, when uninstalling a module, that module's folder is simply deleted and that's it. Since all dependencies are contained in the "black box", there's no need to go hunting for them.
The install command is used to tell CommandBox what you want. Here we ask for the stable release of the ColdBox MVC Platform. "coldbox" is the name of the ForgeBox slug.
Packages should always have a box.json descriptor file inside them. This is especially true of packages installed from endpoints other than Forgebox since they don't have any other metadata available. CommandBox will install any zip file even if it doesn't have a box.json, but this isn't ideal since the name, version, and type of the package must be guessed in that instance.
If you find a package on the internet that doesn't have a box.json, please contact the maintainer and request that they add one or submit a pull request!
ForgeBox supports semantic version ranges for installing packages. Here are some examples:
When installing a ForgeBox package, which is not currently installed, but IS defined already in the box.json with a semantic version range, you will not get the very latest version of that package, but whatever version satisfies the version range in the box.json.
So if you were to seed your box.json with the following:
and then run either
or
You would get the latest version of ColdBox that satisfies the range ^4.1.0.
When you install a package, here are the steps that are taken. Most all of this should be evident by the output streamed to the console during the install process. To get even more juicy details, use the --verbose flag while installing.
CommandBox inspects the ID passed to the install command to determine the endpoint to use.
The matching endpoint is asked to fetch the package represented by the ID.
For example, the ForgeBox endpoint checks the local artifact cache and possibly downloads the package.
If ForgeBox is offline, the best match package will be looked for in your artifacts.
The package is unzipped and its box.json is read
Installation directory is finalized
Contents of package are copied based on the ignore and --production flag
The package is saved as a dependency in the root box.json
The package's dependencies are installed
There are several factors that determine where a package gets installed to. Here are the ways CommandBox determines the install location in order of importance.
The value of the directory parameter passed into the install command by the user.
The value of the installPaths.packageName property set in the project's main box.json by the user. Where packageName is the name of the package you are installing like logbox.
The value of the directory property in the package's box.json by the package author. Note, this must be a path relative to the current working directory (CWD).
Based on the package type convention if the package is a command, coldbox module, commandbox module, plugin, or interceptor. (These default conventions can be overriden on a per-package basis)
If the package being installed is of type lucee-extensions and if the current working directory is found to have a Lucee server in it, the lex file will instead be installed to the server context's deploy folder.
The current working directory (CWD)
Once the installation directory is determined, a folder is created that matches the package's slug which is where the package is finally copied to. If the package's createPackageDirectory property is set to false in the box.json, the package will be copied to the root of the installation directory. An example of this would be a complete application that needs to go in the web root.
If you have a project and want all packages of a certain type to use a different-than-normal default install location, you can override each package type just for that project. Create an installPathConventions key in the containing package's box.json which is an object containing keys for each package type you wish to override package install paths for.
These can be absolute paths, or relative (to the box.json). The install command will check for these when it installs a package. These overrides will ONLY apply to the first level of dependencies. For example, if you set up a modules override to put your app's modules into ../lib/modules, any downstream dependencies of those modules will still use the default install location, unless those modules have their OWN installpathConventions defined.
There are several options you can use to control how a package is installed.
By default, any package you install will be saved as a dependency. To save it as a development dependency instead, use the --saveDev flag.
If you DON'T want the package you're installing to be saved as a dependency pass save=false or negate the save flag as --!save.
When you install a package, all dependencies will be installed. If you want to skip development dependencies, use the --production flag. This will also cause CommandBox to obey the package's ignore property in its box.json.
If you're a glutton for information, or perhaps you just want to debug what's going on, set the --verbose flag to get extra debugging information out of the install command including a list of every file that's installed.
If CommandBox sees the directory that it was going to install into already exists with a newer or equal version of the package inside, it will decline to install again since it would be overwriting what's already there. If you want to install anyway, use the --force flag.
There is a helpful command called forgebox version-debug which will show you what version of a package will be installed without actually installing it. It can also be useful to test a semver range and see what packages it matches.
So, for example, if you wanted to see what ColdBox version would be installed if you were to run
then you can instead run this
You will see output similar to this:
In order to filter the output to only show versions which matched your semantic version, use the --showMatchesOnly flag
