For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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.

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:

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:

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

Publishing to ForgeBox

1

Set Up Version

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

2

Build

For Java modules:

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:

Or use the ForgeBox API directly:

5

Tag the Release

Create a Git tag matching your version:

Module Metadata for ForgeBox

Ensure your box.json includes ForgeBox-specific fields:

Installation After Publishing

Once published, users can install your module:

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

Next Steps

  • Testing — TestBox integration and CI/CD patterns

  • Troubleshooting — Common issues and solutions

Last updated

Was this helpful?