Getting Started

Getting Started

Requirements

• BoxLang 1.19 or newer. The module is built against 1.19.0-snapshot.
• Java 21.
• A BoxLang web runtime: MiniServer, a servlet container or CommandBox.

Install

install-bx-module bx-lens

box install bx-lens

Enable

Lens ships with everything off. It has two surfaces, and you turn each one on by itself in boxlang.json, under modules.bxLens.settings.

{
	"modules": {
		"bxLens": {
			"settings": {
				"bar": { "enabled": true }
			}
		}
	}
}

{
	"modules": {
		"bxLens": {
			"settings": {
				"console": {
					"enabled": true,
					"password": "bxsecret:..."
				}
			}
		}
	}
}

Restart the runtime. Every other setting has a default, so this is all you need. See Configuration for the rest. For a server that real users reach, read Running Lens in production first.

See the bar

Create a page and load it from the same machine.

<bx:output>
	<h1>Hello Lens</h1>
</bx:output>

Open the page. A health strip appears at the bottom.

Click the strip, a chip, or press Ctrl+` to open the panel.

Add a message and a timer from code:

lensMessage( "Page loaded", "info" );
users = lensMeasure( "load users", () => {
	return queryExecute( "SELECT 1 AS id" );
} );

See the BIF reference for all functions.

Open the console

With the console on, open http://localhost:8085/~bxlens/index.bxm (use your own host and port) and sign in. /~bxlens/index.bxm always works. The short form /~bxlens/ also works when the request reaches BoxLang. On MiniServer that needs a pass predicate, see The console URL. The bar also has an Open console button.

Try the demo app

The repository has a harness app that produces every kind of data Lens can show, with the bar and the console both on. See Development and the demo script.

Runtime notes

How the bar is delivered

The bar inlines its CSS, JavaScript and data into the HTML response. That adds about 110 KB to each HTML response and needs no extra network request. The console is a separate page at /~bxlens/index.bxm that serves its own files and makes no request to any other site.

Requirements and limits

• Lens injects into HTML responses (text/html by default), before the last </body>. Other responses are recorded but show no bar. They are kept in the console history.
• Callers must pass the access rules. By default only loopback addresses see the bar (bar.access is "local").
• When a request ends in an uncaught exception or abort, core renders its own error page and Lens cannot inject into it. The request is still recorded in the console history. See Exceptions.

Next steps

• Tour the panels
• Learn the keyboard shortcuts
• Read the security notes
• Set up the console
• Check the license terms