Packages are quite simply a folder that contains some code and a box.json file. A package can be a simple CFC, a self-contained library, or even an entire application. ColdBox and ContentBox modules also make great "smart" packages.
Remember, packages aren't just the things you install into your application, but your application is a package too! That's why when you install something in your app, we'll create a /box.json if it doesn't exist to start tracking your dependencies.
Your box.json file describes your package, dependencies, and how to install it. To turn a boring folder into a sweet package just run the init command in the root of the folder.
That's it. Your folder now has extra meta data in the box.json file that describes it in a way that is meaningful to ForgeBox and CommandBox.
When making a package available on ForgeBox, each version of that package has its own location. Most download locations point to a zip file, that when extracted, contains a folder with a box.json in it. The box.json designates the root of the package. However, the location property of your box.json can be any valid endpoint ID. An example would be:
In that case, the location for version 1.0.0 of this package is the v1.0.0 tag in that GitHub repository.
ForgeBox can store the binaries for your packages in the ForgeBox Cloud. This provides you with an easy way to store multiple versions of your package distributed across the globe.
To utilize ForgeBox Storage, simply set forgeboxStorage as the value of your package's location.
When you publish a package, CommandBox will automatically zip up your package and send it to ForgeBox.
publish CommandWhen you run the publish command from the root of a package, the package will be created on ForgeBox. If the package already exists in ForgeBox, the new version will be added. If the version already exists, the package metadata will be updated.
Most of the data about a package exists in the box.json such as name, slug, version, etc. There are also some files read from disk by convention. The publish command looks by convention for the following files (case insensitive) when publishing
readme - Maps to Package Description
instructions - Maps to Installation Instructions
changelog - Maps to Change Log
Every file is checked for .md, .txt, and no extension in that order.
Below is an example of the commands that would take you from scratch to a published package:
ForgeBox supports private packages. Private packages are only visible to the user who created it.
To create a private package, pass the private flag to the package init command.
init name="My Package" version="1.0.0"{
"name":"my project",
"slug":"my-project",
"version":"1.0.0",
"location":"githubUser/repoName#v1.0.0"
}package set location=forgeboxStorage# Create user (first time only)
forgebox register username password [email protected] firstName lastName
forgebox login username password
# Create package
mkdir mypackage --cd
package init slug=my-package type=modules
bump --major
# Publish it
publish
# Viewable and installable by the world!
forgebox show my-package
install my-packageCommandBox:my-package> package init slug=my-package --private
- Set name = My Package
- Set slug = my-package@username
- Set version = 0.0.0
- Set private = true
- Set shortDescription = A sweet package
- Set ignore = ["**/.*","test","tests"]
Package Initialized & Created /Users/username/code/sandbox/my-package/box.jsonForgeBox.io can be used as a general purpose community extension provider for Lucee 5 compatible extensions. All you need to do is publish your extensions to Forgebox just like you would with any other package, and then anyone who adds https://www.forgebox.io to their Lucee server as an extension provider will be able to see you extension and install any version of it that they choose. This allows anyone to share their extensions with the world without the need to create, host, and maintain their own publish extension provider.
In order to publish you extension (or any other package for that matter) to ForgeBox you just need three things
A forgebox account (use forgebox register if you don’t have one)
A box.json with the correct metadata in your package.
Run the publish command from that folder.
A new package will be created if it doesn’t exist, otherwise it will be updated. A new version will also be created if it doesn’t exist matching the version in your box.json or it will be updated. Review our generic docs on how to creating and publishing packages here:
In your box.json, you’ll want to minimally have the following properties set:
The slug property in your box.json to be the unique GUID of your extension from your manifest file. Lucee's docs state this needs to be a UUID. It needs to match what’s in your manifest or updates won’t work.
The version needs to be the current version of your package that you want to publish. To add a new version, you’ll just update the json and re-run the publish command. One thing to watch out for is that Lucee likes to use the x.y.z.q version format which does not quite match the npm-style x.y.z-prerelease+build
The publish command will pick up any readme.md file in your current directory where you run the publish command and will put it on ForgeBox as the description. This is very handy so make sure you have a good readme so your package home looks good. If you want to update it, simply edit the readme file and re-run the publish command at any time.
Here is the box.json file used for the .
Lucee extensions have additional metadata that can be provided in their manifest that an extension provider reports. These additional properties can be specified in your box.json and the ForgeBox Lucee Extension provider will pick them up and report them. Please refer to the on what each of these do.
lucee-extension-category
lucee-extension-releasetype
lucee-extension-minloaderversion
x.y.zYou want the type property in your json to be lucee-extensions
Set your publicly-acessable thumbnail URL in a thumbnail property in the json
The actual download URL of the lex file needs to be set in the location property in the json. Please note Lucee has some bugs where it doesn’t like servers that don’t set the right content type that it expects. Someone else I was helping had to rename it to a zip file on GitHub so get Lucee to accept it. (A lex file is just a zip file) Perhaps go give a vote on this ticket.
Fill out any other info like name (human readable), author, etc
lucee-extension-mincoreversion
lucee-extension-price
lucee-extension-currency
lucee-extension-disablefull
lucee-extension-trial
lucee-extension-promotionlevel
lucee-extension-promotiontext
{
"name":"Ortus Couchbase Cache",
"version":"3.0.0",
"author":"Brad Wood",
"location":"https://s3.amazonaws.com/downloads.ortussolutions.com/ortussolutions/couchbase-extension/couchbase-cache-3.0.0.lex",
"slug":"14B0C2A7-5CFC-4606-9167C93959A8B82C",
"description":"A Lucee caching extension allow you to connect to a Couchbase Cluster for caching, session, and client storage",
"type":"lucee-extensions",
"thumbnail":"https://s3.amazonaws.com/downloads.ortussolutions.com/ortussolutions/couchbase-extension/couchbase-cache-logo.png"
}We've seen how any folder can be turned into a package with the init command. Initial properties can be set as named parameters to the init command.
The init command can be called more than once on a package and it will keep existing properties and only overwrite the ones you specify.
Once you've created your box.json, you can edit the file directly, or there are other commands to help manage it programmatically.
Each of these commands support tab-complete that is dynamic based on what properties are currently in your box.json.
The package show command can be used to out put any part of the box.json. You can specifiy any property name from your box.json.
Outputs package name and keywords
Nested attributes may be accessed by specifying dot-delimited names or using array notation. If the accessed property is a complex value, the JSON representation will be displayed
Outputs testbox runner(s)
Outputs the first testbox notify E-mail
Output the entire box.json
using JmesPath with package show
Any property in your box.json can be set from the command line with the package set command.
Set package name
Nested attributes may be set by specifying dot-delimited names or using array notation. If the set value is JSON, it will be stored as a complex value in the box.json.
Set the repository type.
Set first testbox notify E-mail.
Set multiple params at once by passing as many named parameters as you like.
Set a complex value as JSON.
Objects and arrays can be appended to using the append parameter. This only works if the property and incoming value are both of the same complex type.
Add an additional contributor to the existing contributors array.
Add an additional dependency to the existing dependencies object.
If you need to remove a property entirely from your box.json, use the package clear command. It also works on nested properties using "dot" or array notation.
Remove the package description entirely.
init name="My Package" version=1.0.0package show name
package show keywordspackage show testbox.runnerpackage show testbox.notify.emails[1]package showpackage show jq:slug
# grab contributors and split each result by spaces
package show "jq:contributors|split(@,' ')"
# get an array of all engine names
package show "jq:engines[].type"
# filter struct values and add in an additional value => { "myprop":"test", "name":"MyPackageName" }
package show "jq:{name:name, myprop:'test'}"
# return struct values in an array => [MyPackageName,2.4]
package show "jq:[name,version]"package set name=myPackagepackage set repository.type=Gitpackage set testbox.notify.email[1]="[email protected]"package set name=myPackage version="1.0.0.000" author="Brad Wood" slug="foo"package set testbox.notify.emails="[ '[email protected]', '[email protected]' ]"package set contributors="[ '[email protected]' ]" --appendpackage set dependencies="{'cbcommons':'1.0.0'}" --appendpackage clear description