> 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/mappings.md).

# Mappings & Class Resolution

Every BoxLang module receives automatic mappings for class resolution and optional web access. Understanding these mappings is essential for importing classes and serving web content.

## Internal Module Mapping

When a module is registered, BoxLang creates an **internal mapping** for class resolution:

| Property       | Value                    | Purpose                            |
| -------------- | ------------------------ | ---------------------------------- |
| **Path**       | `bxModules.{moduleName}` | Internal class path prefix         |
| **Physical**   | Module root directory    | Where classes/BIFs/components live |
| **Web Access** | ❌ No                     | Only for class resolution          |

For a module named `myModule`, the internal mapping `bxModules.myModule` points to the module root. This is used for class resolution only — it's not web-accessible.

## Public Web Mapping

For serving static files via HTTP, BoxLang creates a **public mapping**:

| Property     | Default                     | Customizable            |
| ------------ | --------------------------- | ----------------------- |
| **Folder**   | `{moduleRoot}/public/`      | ✅ `this.publicMapping`  |
| **URL Path** | `/bxModules/{name}/public/` | ✅ Override mapping name |

Files in `myModule/public/css/style.css` are accessible at:

```
http://yourserver.com/bxModules/myModule/public/css/style.css
```

## Customizing Mappings

Override defaults in your module descriptor:

{% tabs %}
{% tab title="ModuleConfig.bx" %}

```js
class {
    // Override internal mapping name
    this.mapping = "customName";

    // Override public folder
    this.publicMapping = {
        name: "assets",           // URL: /bxModules/customName/assets/
        path: "web/static",       // Physical path relative to module root
        external: false           // true = absolute path
    };
}
```

{% endtab %}

{% tab title="Java @BoxModule" %}

```java
@BoxModule(
    mapping = @BoxMapping("customName"),
    publicMapping = @BoxMapping(
        name = "assets",
        path = "web/static",
        external = false
    )
)
public class MyModuleConfig implements IModuleConfig { }
```

{% endtab %}
{% endtabs %}

## The @moduleName Notation

BoxLang provides a powerful syntax for explicitly addressing classes from specific modules using the `@moduleName` suffix. This improves performance and eliminates ambiguity.

### Why Use @moduleName?

{% columns %}
{% column %}
**Without @moduleName:**

```js
import models.UserService
```

* BoxLang searches ALL modules
* Slower with many modules loaded
* Ambiguous if duplicates exist
  {% endcolumn %}

{% column %}
**With @moduleName:**

```js
import models.UserService@myModule
```

* Direct lookup in the specified module
* Faster resolution
* No ambiguity
  {% endcolumn %}
  {% endcolumns %}

### Importing BoxLang Classes

```js
// Import from a specific module
import models.ActiveEntity@cborm
entity = new ActiveEntity()

// Import with alias
import models.ActiveEntity@cborm as AE
entity = new AE()

// Import component
import components.DataTable@bx-ui-forms
table = new DataTable()
```

### Importing Java Classes from Modules

The same notation works for Java classes packaged in modules:

```js
// Import Java class from module
import org.owasp.esapi.ESAPI@bx-esapi
encoder = ESAPI.encoder()

// Import with alias
import org.owasp.esapi.ESAPI@bx-esapi as SecurityAPI
encoder = SecurityAPI.encoder()

// Create instance directly
encoder = new java:org.owasp.esapi.reference.DefaultEncoder@bx-esapi()
```

### Using createObject()

```js
// Create BoxLang class from a module
service = createObject( "component", "models.UserService@myModule" )

// Create Java class from a module
driver = createObject( "java", "com.mysql.cj.jdbc.Driver@bx-mysql" )
```

{% hint style="warning" %}
The `@moduleName` notation requires the module to be **loaded and activated**. If the module isn't loaded, you'll get a class-not-found error.
{% endhint %}

## Class Loading Hierarchy

When resolving a class with `@moduleName`, BoxLang searches:

1. **Module's compiled classes** (`modules.{moduleName}` package prefix)
2. **Module's `libs/` folder** (JAR dependencies)
3. **Parent class loader** (runtime classes — fallback)

This isolation ensures modules don't interfere with each other's dependencies.

## Custom Class Resolvers

Modules can register custom class resolvers with unique prefixes (extending the built-in `bx:` and `java:` resolvers). See [Advanced Collaboration](/boxlang-framework/module-development/advanced-collaboration.md#custom-class-resolvers) for details.

## Best Practices

{% stepper %}
{% step %}

### Use @moduleName for Clarity

Always use `@moduleName` when importing classes from modules to avoid ambiguity and improve performance.

✅ `import models.UserService@myModule` ❌ `import models.UserService`
{% endstep %}

{% step %}

### Keep Public Folders Organized

Structure your `public/` folder logically:

```
public/
├── css/
├── js/
├── images/
└── templates/
```

{% endstep %}

{% step %}

### Document Your Mappings

In your module's README, document what mappings are created and how to import your classes.
{% endstep %}
{% endstepper %}

## Next Steps

* [Configuration](/boxlang-framework/module-development/configuration.md) — Module settings and runtime overrides
* [Advanced Collaboration](/boxlang-framework/module-development/advanced-collaboration.md) — System settings providers and class resolvers
* [Capabilities](/boxlang-framework/module-development/capabilities.md) — BIFs, components, services, and more


---

# 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/mappings.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.