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.

init

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

init name="My Package" slug=my-package version=1.0.0

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

init --wizard

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 Contact Us!

{
    "name" : "Package Name",
    // ForgeBox unique slug
    "slug" : "",
    // semantic version of your package
    "version" : "1.0.0.buildID",
    // author of this package
    "author" : "Luis Majano <[email protected]>",
    // location of where to download the package, overrides ForgeBox location
    "location" : "URL,Git/svn endpoint,etc",
    // install directory where this package should be placed once installed, if not
    // defined it then installs were the CommandBox command was executed.
    "directory" : "",
    // This boolean bit determines if the container directory will contain a sub-directory according to
    // the package slug name, the default is true
    "createPackageDirectory" : "boolean",
    // If this is set, then we will use this name for the package sub-directory, instead of the slug name
    "packageDirectory" : ""
    // project homepage URL 
    "Homepage" : "URL",
    // documentation URL
    "Documentation" : "URL",
    // source repository, valid keys: type, URL 
    "Repository" : { 
        "type" : "git,svn,mercurial", "URL" : ""
    },
    // bug issue management URL
    "Bugs" : "URL",
    // ForgeBox short description
    "shortDescription" : "short description",
    // ForgeBox big description, if not set it looks for a Readme.md, Readme, Readme.txt
    "description" : "",
    // Install instructions, if not set it looks for a instructions.md, instructions, instructions.txt
    "instructions" : "",
    // Change log, if not set, it looks for a changelog.md, changelog or changelog.txt
    "changelog" : ""
    // ForgeBox contribution type
    "type" : "1 from forgebox available types",
    // ForgeBox keywords, array of strings
    "keywords" : [ "groovy", "module" ],
    // Bit that designates the package as a private ForgeBox package.
    // Private packages are not publicly accessible, but still
    // offer all the benefits of ForgeBox.
    "private" : "boolean",
    // cfml engines it supports, type and version
    "engines" : [
        { "type" : "railo", "version" : ">=4.1.x" },
        { "type" : "lucee", "version" : ">=4.5.x" },
        { "type" : "adobe", "version" : ">=10.0.0" }
    ],
     // default project URL if not using our start server commands
    "ProjectURL" : "http://railopresso.local/myApp",
    // license array of licenses it can have
    "License" : [
        { "type" : "MIT", "URL" : "" }
    ]
    // contributors array of strings or structs: name,email,url 
    "Contributors" : [ "Luis Majano", "Luis Majano <[email protected]>", {name="luis majano", email="", url=""} ],
    // dependencies, a shortcut for latest version is to use the * string
    "Dependencies" : {
        "coldbox" : "x" // latest version from ForgeBox
        "slug" : "version", // a specific version from ForgeBox
        "slug" : "local filepath", //disallowed from forgebox registration
        "slug" : "URL",
        "slug" : "Git/svn endpoint"
    },
    // only needed on development
    "DevDependencies" : {
        // Same as above, but not installed in production
    },
    // Tracks install locations so uninstall can work.
    "installPaths" : {
        "coldbox" : "coldbox" // relative to package root (no leading slash)
        "feeds" : "modules/feeds", // relative to package root (no leading slash)
        "Name" : "C:\\foo\\bar" // Outside root, so full path
    },
    // array of strings of files to ignore when installing the package similar to .gitignore pattern spec 
    "ignore" : [ "logs/*", "readme.md" ]
    // testbox integration
    "testbox" : {
        // the uri location of the test runner for is app or several with slug names
        "runner" : [
            { "cf9"   : "http://cf9cboxdev.jfetmac/coldbox/testing/runner.cfm" },
            { "railo" : "http://railocboxdev.jfetmac/coldbox/testing/runner.cfm" }
        ],
        "runner" : ""
        "Labels" : [],
        "Reporter" : "",
        "ReporterResults" : "/test/results"
        "Bundles" : [ "test.specs" ]
        "Directory" : { mapping : "test.specs", recurse: true }, 
        // directories or files to watch for changes, if they change, then tests execute
        "Watchers" : [ "/model" ] ,
        // after tests run we can do a notification report summary
        "Notify" : { 
            "Emails" : [],
            "Growl" : address,
            // URL to hit with test report
            "URL" : ""
        }
    }
}

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

name

string

Name of the package. Short, but descriptive.

package set name="Whiz Bang Module"
package show name

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.

package set slug="whiz-bang"
package show slug

version

string

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

package set version=1.0.0.0000
package show version

author

string

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

package set author="Brad Wood <[email protected]>"
package show author

shortDescription

string

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

package set description="Install this module to add a bit of Whiz Bang to your app."
package show 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.

package set private=false
package show private

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.

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.

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.

"engines" : [
    { "type" : "railo", "version" : ">=4.2.1" },
    { "type" : "adobe", "version" : ">=10.0.0" }
]

package set engines="[ { type : 'lucee', version : '>=4.5.x' } ]" --append
package show engines

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.

package set defaultEngine=lucee
package show defaultEngine

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

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

"devDependencies" : {
    "testbox" : "2.0"
}

package set devDependencies="{ cbdebugger : '1.0.0' }" --append
package show devDependencies

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.

package set description="This is a \n cool module \n please install it."
package show description

instructions

string

Tell the user how to install and use your package.

package set instructions="1) Unwrap packaging \n 2) Apply liberally to affected site \n 3) profit!"
package show instructions

changelog

string

A list of the changes this package has gone through.

package set changelog="1.0 initial version \n 1.1 Bug fixes"
package show changelog

keywords

array

List words that describe your package as an array of keywords.

package set keywords="[ 'cool', 'amazing', 'whiz', 'bang', 'cheese whiz' ]" --append
package show keywords

license

array of objects

Let the world know what license your package is released under. This property is an array of objects where each object represents a single license. Your package can have more than once license.

The license object will have a type and URL key. Examples of license types are MIT, GPL, Apache 2.0, etc. A valid list of licenses might look like this:

"license" : [
        { "type" : "MIT", "URL" : "http://opensource.org/licenses/MIT" },
        { "type" : "GPL-3.0", "URL" : "http://opensource.org/licenses/GPL-3.0" }

    ]

package set license="[ { type : 'MIT', URL: 'http://opensource.org/licenses/MIT' } ]" --append
package show license

contributors

array

Give a shout-out here to everyone who helped with your package. This is an array, and you can put strings it containing names and/or E-mail addresses, or you a objects to the array containing keys such as name and email.

"contributors" : [
        "Mickey Mouse",
        "Minny Mouse <[email protected]>",
        { "name" : "Daffy Duck", "email" : "[email protected]" }

    ]

package set contributors="[ 'Goofy' ]" --append
package show contributors

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.

package set directory=lib
package show directory

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.

package set type=modules
package show type

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

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

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

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

• a/*/z will match a/b/z but not a/b/c/z

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

package set ignore="['**/.*','test','tests']" --append
package show ignore

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.

"installPaths" : {
    "coldbox" : "coldbox" // relative to package root (no leading slash)
    "feeds" : "modules/feeds", // relative to package root (no leading slash)
    "Name" : "C:\foo\bar" // Outside root, so full path
}

package set installPaths="{ foo : 'lib/foo' }" --append
package show installPaths

or

package set installPaths.logbox=../logbox/
package show installPaths

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.

package set createPackageDirectory=true
package show createPackageDirectory

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.

package set packageDirectory=coldbox
package show packageDirectory