Getting Started

Step-by-step guide to create your first BoxLang module using templates

Create your first BoxLang module in minutes using our official templates. Choose between pure BoxLang for rapid development or Java + BoxLang for full runtime integration.

Pick Your Path

🟦 Pure BoxLang

1. Clone the Template

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

2. Customize Metadata

Edit box.json with your module details:

{
  "name": "My Amazing Module",
  "version": "1.0.0",
  "slug": "bx-my-module",
  "shortDescription": "Does amazing things",
  "boxlang": {
    "minimumVersion": "1.0.0",
    "moduleName": "myModule"
  }
}

3. Configure ModuleConfig.bx

class {
    property name="moduleRecord";
    property name="boxRuntime";
    property name="log";

    this.version     = "1.0.0";
    this.mapping     = "myModule";
    this.author      = "Your Name";
    this.description = "My amazing module";

    function configure() {
        settings = {
            loadedOn: now(),
            loadedBy: "Your Name"
        };

        interceptors = [];
        customInterceptionPoints = [];
    }

    function onLoad() {}
    function onUnload() {}
}

4. Add Your First BIF

Create bifs/HelloWorld.bx:

/**
 * Returns a greeting message
 *
 * @param name The name to greet
 * @return Greeting string
 */
function invoke( required string name ) {
    return "Hello, #name#! Welcome to BoxLang modules."
}

5. Test Locally

// Load the module
moduleService.loadModule(
    createObject( "java", "java.nio.file.Paths" ).get( "/path/to/my-module" )
)

// Use your BIF
result = helloWorld( "Developer" )
writeOutput( result )

✅ Done! No build step required — your module is ready to distribute.

☕ Java + BoxLang

Module Folder Structure

Pure BoxLang

my-module/
├── box.json              # Module metadata
├── ModuleConfig.bx        # Module descriptor
├── bifs/                  # BoxLang BIFs
│   └── HelloWorld.bx
├── components/            # BoxLang components (tags)
│   └── MyTag.bx
├── interceptors/          # BoxLang interceptors
│   └── Listener.bx
├── libs/                  # External JARs
├── public/                # Static web assets
└── tests/                 # TestBox tests

Java + BoxLang

Available Template Injections

When writing your ModuleConfig.bx, BoxLang automatically injects these properties:

Property	Type	Purpose
moduleRecord	ModuleRecord	The module's registration record
boxRuntime	BoxRuntime	The BoxLang runtime singleton
functionService	FunctionService	Register/query BIFs
componentService	ComponentService	Register/query components
interceptorService	InterceptorService	Register/announce interceptors
asyncService	AsyncService	Async execution and futures
schedulerService	SchedulerService	Scheduled task management
datasourceService	DatasourceService	Datasource and JDBC
cacheService	CacheService	Cache store management
log	BoxLangLogger	Module-specific logger

All injected services are also available from boxRuntime.getService( "ServiceName" ) if you need them outside of ModuleConfig.bx.

Next Steps

• Module Descriptor — Deep dive into box.json and ModuleConfig.bx
• Architecture — Understand module isolation and class loading
• Capabilities — Explore what modules can provide