Module Development

Complete guide to creating, configuring, and publishing BoxLang modules using pure BoxLang or Java

Build extensible plugins for the BoxLang runtime through an isolated, convention-based module system. Choose between pure BoxLang for rapid development or Java + BoxLang for performance-critical integrations.

All examples in this guide reference real, open-source modules from the ortus-boxlang GitHub organization. The modules listed under Modules focus on using existing modules — this section focuses on building them.

Choose Your Approach

🟦 Pure BoxLang

No compilation required. Perfect for utilities, configurations, and simple BIFs/components.

Best for: Rapid prototyping, simple logic, no external dependencies

• ✅ BIFs (.bx files)
• ✅ Components (.bx files)
• ✅ Interceptors (via configure())
• ✅ Custom interception points
• ✅ Settings & configuration
• ✅ Public web folders
• ✅ Libs/JARs
• ❌ Services (Java only)
• ❌ Schedulers (Java only)
• ❌ Cache Providers (Java only)
• ❌ JDBC Drivers (Java only)

→ Start with Pure BoxLang

☕ Java + BoxLang

What Modules Can Provide

BoxLang or Java

• ✅ BIFs — Custom built-in functions
• ✅ Components — XML-style tags (bx:mytag)
• ✅ Interceptors — Event listeners
• ✅ Settings — Module configuration
• ✅ Mappings — URL routing & class resolution
• ✅ Public Folders — Static web assets
• ✅ Libs — JAR dependencies

Java Only

• ✅ Services — Global runtime services
• ✅ Schedulers — Cron-like scheduled tasks
• ✅ Cache Providers — Custom caching backends
• ✅ JDBC Drivers — Database connectivity
• ✅ System Setting Providers — Custom getSystemSetting() sources
• ✅ Class Resolvers — Custom prefix:ClassName resolution

Quick Navigation

Topic	Description
Getting Started	Choose your approach, use templates, create your first module
Architecture	Understand module isolation, class loaders, and discovery
Module Descriptor	Configure box.json, ModuleConfig.bx, and Java IModuleConfig
Lifecycle	Registration → Activation → Running → Deactivation
Capabilities	BIFs, components, interceptors, services, and more
Mappings & Class Resolution	Module mappings, @moduleName notation, and class loading
Configuration	Settings, runtime overrides, dependency management
Advanced Collaboration	System settings providers, custom resolvers, inter-module communication
Packaging & Publishing	Build output, ForgeBox workflow, versioning
Testing	TestBox integration, CI/CD patterns
Troubleshooting	Common issues and solutions

Open Source Module Examples

Learn from production-ready modules in our ecosystem:

Pure BoxLang

Module	Purpose	Complexity
bx-ai	AI integration helpers	🟢 Simple
bx-csrf	CSRF token management	🟢 Simple
bx-jwt	JWT token handling	🟡 Medium
bx-ftp	FTP client operations	🟡 Medium
bx-image	Image manipulation	🟡 Medium
bx-yaml	YAML parsing/generation	🟢 Simple
bx-ini	INI file handling	🟢 Simple
bx-markdown	Markdown rendering	🟡 Medium
bx-wddx	WDDX serialization	🟢 Simple

Java + BoxLang

JDBC Drivers

Advanced

Browse all 40+ open-source modules at github.com/ortus-boxlang

Module Templates

Start with official templates to bootstrap your module. Both templates are available on GitHub:

Pure BoxLang Template:

git clone https://github.com/ortus-boxlang/boxlang-module-template-bx.git my-module
cd my-module

Java + BoxLang Template:

git clone https://github.com/ortus-boxlang/boxlang-module-template.git my-module
cd my-module
./gradlew build

The templates include placeholder files and configuration you can customize. See Getting Started for a detailed walkthrough.

Next Steps

1. Choose Your Approach — Decide between pure BoxLang or Java+BoxLang
2. Understand the Architecture — Learn about module isolation and discovery
3. Explore Real Examples — Study production modules like bx-ai and bx-compat-cfml
4. Start Building — Create your first module with our templates

---

Need help? Check out the Troubleshooting Guide for common issues and solutions.