Publishing modules to ForgeBox

Standard process for cutting a release and publishing a BoxLang/ColdBox module. CommandBox handles the version bump, git tag, and push via box.json scripts — don't do these manually, hook them.

1. Repo setup

Module root needs box.json and ModuleConfig.bx (or .cfc) plus whatever structure the module needs (models/, handlers/, etc.). The repo is the package. No separate dist folder unless it's a compiled Java+BoxLang module.

2. box.json

This is what box publish and box version read. Keep it current, and this is also where the release automation lives:

{
  "name": "My Module",
  "slug": "bx-my-module",
  "version": "1.2.0",
  "type": "boxlang-modules",
  "author": "...",
  "repository": { "type": "git", "URL": "https://github.com/you/bx-my-module" },
  "scripts": {
    "preVersion": "testbox run",
    "postVersion": "package set location='you/bx-my-module#v`package version`'",
    "postPublish": "!git push --follow-tags"
  }
}

slug is unique on ForgeBox — don't touch it once claimed.

What the scripts do

• preVersion — runs before box version sets the new version. Use it to run tests; bail if they fail.
• postVersion — runs after the version is bumped but before the git tag is created. Used here to keep the package's install location pointed at the new tag.
• postPublish — runs after box publish. !git push --follow-tags pushes the commit and the tag together.

Full interception point order for box version: preVersion → version set in box.json → postVersion → git tag created → onRelease.

3. Commit your changes

git add .
git commit -m "..."

Don't bump the version manually — that's step 4.

4. Bump the version

box version --patch   # or --minor / --major

This runs preVersion, updates box.json, runs postVersion, then creates the git tag (v1.2.0 etc.) and fires onRelease. No manual git tag.

5. Publish

box publish

Requires box login / API token already set up. Reads box.json for slug/version. postPublish fires after — this is what pushes the commit and tag to GitHub via !git push --follow-tags.

6. Verify

box search bx-my-module

Or just check the ForgeBox listing page and confirm the tag landed on GitHub. Confirm the new version shows up before calling it done.