Packaging & Publishing

Build, package, and publish your BoxLang module to ForgeBox

Build your module for distribution and publish it to ForgeBox so others can install it via CommandBox.

Build Output

Java + BoxLang Modules

Run the Gradle build:

./gradlew build

Output is in build/module/:

build/module/
├── box.json
├── changelog.md
├── readme.md
├── ModuleConfig.bx
├── libs/
│   └── my-module-all.jar    # Shadow JAR with all dependencies
├── bifs/
│   └── *.bx                 # Any BoxLang BIFs
└── components/
    └── *.bx                 # Any BoxLang components

The shadow JAR bundles your Java code AND all dependencies into a single artifact.

The build uses the com.gradleup.shadow plugin to create a fat JAR. ServiceLoader entries are auto-generated by the gradle-serviceloader plugin.

Pure BoxLang Modules

Distribution Files

Ensure these files are present in your distribution:

File	Purpose	Required
box.json	Package metadata	✅
ModuleConfig.bx	Module descriptor	✅
readme.md	Module documentation	⚠️
changelog.md	Release notes	⚠️
libs/	JAR dependencies	If applicable

The ignore Pattern

Use box.json ignore to exclude development files from distribution:

{
  "ignore": [
    "**/.*",
    "settings.gradle",
    "gradlew.bat",
    "gradlew",
    "build.gradle",
    "/src/**",
    "gradle/**",
    "tests/**",
    ".github/**"
  ]
}

Version Management

Use semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR — Breaking changes
• MINOR — New features (backward compatible)
• PATCH — Bug fixes (backward compatible)

For Gradle projects, set the version in gradle.properties:

version=1.2.0

For version placeholders during development, use @build.version@:

{
  "version": "@build.version@[e-mail]@"
}

Publishing to ForgeBox

1

Set Up Version

Update box.json and gradle.properties with your release version.

2

Build

For Java modules:

./gradlew build -x test

For pure BoxLang modules, no build needed.

3

Create Distribution

For Java modules, the distribution is in build/distributions/ as a ZIP.

For pure BoxLang, zip the module directory.

4

Publish to ForgeBox

Using CommandBox:

box publish slug=bx-my-module version=1.2.0 zip=/path/to/dist.zip

Or use the ForgeBox API directly:

curl -X POST https://www.forgebox.io/api/v1/entry \
  -F "slug=bx-my-module" \
  -F "version=1.2.0" \
  -F "file=@dist.zip"

5

Tag the Release

Create a Git tag matching your version:

git tag v1.2.0
git push origin v1.2.0

Module Metadata for ForgeBox

Ensure your box.json includes ForgeBox-specific fields:

{
  "name": "My Amazing Module",
  "version": "1.2.0",
  "slug": "bx-my-module",
  "shortDescription": "Does amazing things",
  "type": "boxlang-modules",
  "keywords": ["boxlang", "module", "amazing"],
  "homepage": "https://github.com/ortus-boxlang/bx-my-module",
  "documentation": "https://boxlang.ortusbooks.com/boxlang-framework/modularity/",
  "repository": {
    "type": "git",
    "URL": "https://github.com/ortus-boxlang/bx-my-module"
  },
  "bugs": "https://github.com/ortus-boxlang/bx-my-module/issues",
  "license": [
    {
      "type": "Apache-2.0",
      "URL": "https://www.apache.org/licenses/LICENSE-2.0"
    }
  ]
}

Installation After Publishing

Once published, users can install your module:

box install bx-my-module

Or declare it as a dependency in their box.json:

{
  "dependencies": {
    "bx-my-module": "^1.2.0"
  }
}

Next Steps

• Testing — TestBox integration and CI/CD patterns
• Troubleshooting — Common issues and solutions