> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/module-development/packaging-publishing.md).

# Packaging & Publishing

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

## Build Output

{% tabs %}
{% tab title="Java + BoxLang Modules" %}
Run the Gradle build:

```bash
./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.

{% hint style="info" %}
The build uses the `com.gradleup.shadow` plugin to create a fat JAR. ServiceLoader entries are auto-generated by the `gradle-serviceloader` plugin.
{% endhint %}
{% endtab %}

{% tab title="Pure BoxLang Modules" %}
No build step required. Your module IS the distributable:

```
my-module/
├── box.json
├── ModuleConfig.bx
├── bifs/           # BoxLang BIFs
├── components/     # BoxLang components
├── interceptors/   # BoxLang interceptors
├── libs/           # External JARs
└── public/         # Web assets
```

Simply zip the directory for distribution.
{% endtab %}
{% endtabs %}

## 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:

```json
{
  "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`:

```properties
version=1.2.0
```

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

```json
{
  "version": "@build.version@+@build.number@"
}
```

## Publishing to ForgeBox

{% stepper %}
{% step %}

### Set Up Version

Update `box.json` and `gradle.properties` with your release version.
{% endstep %}

{% step %}

### Build

For Java modules:

```bash
./gradlew build -x test
```

For pure BoxLang modules, no build needed.
{% endstep %}

{% step %}

### Create Distribution

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

For pure BoxLang, zip the module directory.
{% endstep %}

{% step %}

### Publish to ForgeBox

Using CommandBox:

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

Or use the ForgeBox API directly:

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

{% endstep %}

{% step %}

### Tag the Release

Create a Git tag matching your version:

```bash
git tag v1.2.0
git push origin v1.2.0
```

{% endstep %}
{% endstepper %}

## Module Metadata for ForgeBox

Ensure your `box.json` includes ForgeBox-specific fields:

```json
{
  "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:

```bash
box install bx-my-module
```

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

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

## Next Steps

* [Testing](/boxlang-framework/module-development/testing.md) — TestBox integration and CI/CD patterns
* [Troubleshooting](/boxlang-framework/module-development/troubleshooting.md) — Common issues and solutions


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/module-development/packaging-publishing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.