The box.json file must be in your root of your project and it is a JSON file that describes your project, dependencies, development dependencies, installation data, and CommandBox command data.

Note Please note that you can add as many settings or alter the box.json structure to meet your needs when developing commands. This makes our descriptor incredibly flexible.

Initialize a package

To initialize any folder as a package, run the init command.

You can pass as many properties to the init command as you want using named parameters.

You can also do a question/answer style wizard by adding the --wizard flag.

Sample box.json

Below you will see all the possible options that we currently support in CommandBox. Note, not all have been implemented yet. If you have suggestions or updates to our package descriptor, please do not hesitate to !

These properties affect how and where the package is installed.

directory

string

The directory, relative to the web root, that the package will be installed to. This will override the convention directory based on the type property. See package installation for more details on where packages install to.

type

string

The ForgeBox type of the package. See list of available types with the forgebox types command. This can determine the directory the package is installed to. For instance, a type of modules goes in the site's /modules directory.

ignore

array

An array of file/folder globbing patterns that follow the .gitIgnore syntax to NOT be copied when doing a --production install.

End a pattern with a slash to only match a directory. Start a pattern with a slash to start in the root.

• foo will match any file or folder in the directory tree

• /foo will only match a file or folder in the root

• foo/ will only match a directory anywhere in the directory tree

Use a single * to match zero or more characters INSIDE a file or folder name (won't match a slash).

• foo* will match any file or folder starting with foo

• foo*.txt will match any file or folder starting with foo and ending with .txt

Use a double ** to match zero or more characters including slashes. This allows a pattern to span directories.

• a/**/z will match a/z and a/b/z and a/b/c/z

installPaths

object

This is an object of string values where each key is the slug of an installed package and the value is the path the package is installed to. In most cases, this will be managed automatically by the install and uninstall command. If you want to override the directory property on one of your dependencies, you can configured an install path prior to installing the package and it will be used.

Install paths can be a directory relative to the web root (no leading slash) or a full path starting with a drive root.

or

createPackageDirectory

boolean

By default when a package is installed, a directory is created in the install path that is named after the package slug. Setting createPackageDirectory to false will skip the creation of that folder and dump the contents of the package right into the install path.

An example of this would be a full application that is the entire web root. Another example would be an interceptor that gets put directly in the interceptors folder.

Note, when this is set to false, no path will be added to the installpaths directory and the package cannot be removed by the uninstall command.

packageDirectory

string

By default when a package is installed, a directory is created in the install path that is named after the package slug. If a packageDirectory property is set, the folder is named after it instead of the slug.

An example would be the coldbox-be slug that still needs to install into a folder called coldbox. You shouldn't need to use this setting.

There are a number of URLs associated with your package that you can specify with these properties.

location

string

The location of where to download this package. Needs to point to a zip file containing the package.

homepage

string

The homepage for your product. It's fine if this is just the GitHub page. A nice readme can make for a good homepage.

documentation

string

This is where users can go to find documentation on how to use your package. Can be a wiki, HTML docs, etc.

repository

object

This describes the repository used for source control with this package. Object needs a type and URL key. Examples of type would be Git, SVN, Mercurial, etc.

bugs

string

This is the URL where developers can go to report bugs in your package. We know you NEVER write bugs in your software, but it's just a formality so humor us :)

projectURL

string

This is the URL you visit to browse to this actual project code once it is running.

testbox

object

This object stored configuration information used by the TestBox BDD and xUnit testing library. The data is accessed by commands in the testbox command namespace.

testbox.runner

string or array

testbox.runner can be a simple string that contains the full runner URL.

testbox.runner can alternatively be an array of objects containing "named" runner URLs.

More...

Our box.json template shows other placeholder properties inside the testbox object, but only runner is implemented for now.

In the future, the testbox object may be moved into a separate JSON file for organizational purposes.

These properties go a little farther in describing your package and what it is.

description

string

The full description of your package. Feel free to use line breaks, HTML, or football analogies.

dependencies

object

This object tracks the other packages that are required to run the project. Packages are added here automatically by the install ID command, but you can also manually add them and just type install to install them.

The key is the unique slug of the package and the value is the a semvar range, local directory, URL to a zip, or a source control URL.

"dependencies" : {
    "coldbox" : "x" // latest version from ForgeBox
    "cborm" : "1.0.1", // a specific version from ForgeBox
    "private-package" : "C:\\libs\\foo", // local folder
    "private-package2" : "C:\\libs\\foo.zip", // local file
    "baz" : "http://site.com/baz.zip", // URL to zip file
    "cbcsrf" : "git://github.com/ColdBox/cbox-csrf.git"  // Git endpoint
}

package set dependencies="{ coldbox : '4.0.0' }" --append
package show dependencies

devDependencies

object

Development dependencies operate the same as regular ones, expect they are not required to use this project. Instead, they are only required if you plan to do development on the project. These usually including testing libraries, etc.

The install command will save dependencies here when you use the --saveDev flag. These packages will be skipped when you run install --production

These properties affect how the embedded server starts. These settings are now deprecated in favor of the new server.json file.

defaultPort

number

This is the HTTP port the server will be started on when you use the start command. Specifying the port parameter on the start command will override this.

package set defaultPort=8080
package show defaultPort

This setting is deprecated in favor of the port property of server.json. CommandBox will use this setting still if there is no port in server.json and a port argument is not specified with the start command.

engines

array of objects

This represents a list of CF engines your project supports and their version with a semvar range.

This data is informational only and not yet used by the embedded server

defaultEngine

string

The default CF engine for the start command to use.

This data is informational only and not yet used by the embedded server

The following box.json properties provide basic information about what your package is.

name

string

Name of the package. Short, but descriptive.

slug

string

The unique slug for this package. Cannot contain spaces or special characters. Can contain a hyphen. Use the forgebox slugcheck command to see if this slug is already in use. This is what people will use when installing your package from ForgeBox.

version

string

The semantic version of your package following the pattern major.minor.patch.build. Ex: 2.3.5.0012

author

string

The name of the author of the module as a string.

shortDescription

string

Describes what this package is in a couple sentences. Save the dissertation for the description.

private

boolean

A flag that designates if this package is a ForgeBox private package. ForgeBox private packages are not publicly accessible, but offer all the benefits of ForgeBox. Private packages will be a paid feature for ForgeBox Pro subscribers, though the feature is currently available to all users for free.