| name | boxlang-runtime-wasm-in-the-browser |
| description | Use this skill when compiling BoxLang to WebAssembly or JavaScript ES modules for use in web browsers and Node.js using MatchBox's --target js or --target wasm flags, integrating with HTML pages, bundlers (Webpack/Vite), and Node.js projects. |
BoxLang WASM in the Browser
Overview
MatchBox can compile BoxLang source to browser-compatible output via two modes:
| Mode | Flag | Output | Best For |
|---|
| ES Module (recommended) | --target js | .js + .wasm | Browsers, Node.js, bundlers |
| Raw WASM | --target wasm | .wasm | Custom loaders, advanced bundling |
All top-level BoxLang functions are automatically exported, regardless of access modifier.
Mode 1: --target js — ES Module (Recommended)
matchbox --target js my_lib.bxs
The generated .js file is an ES module wrapper. The .wasm file is loaded automatically.
Browser Usage
<!DOCTYPE html>
<html>
<head>
<title>BoxLang in the Browser</title>
</head>
<body>
<script type="module">
import { greet, calculateTotal } from './my_lib.js'
const message = greet("World")
document.getElementById("output").textContent = message
const total = calculateTotal([ 10.99, 5.49, 3.00 ])
console.log("Total:", total)
</script>
<div id="output"></div>
</body>
</html>
BoxLang source (my_lib.bxs)
function greet( name ) {
return "Hello, " & name & "!"
}
function calculateTotal( prices ) {
return prices.reduce( ( sum, price ) -> sum + price, 0 )
}
Node.js Usage
import { greet, calculateTotal } from './my_lib.js'
console.log( greet( "Node.js" ) )
console.log( calculateTotal([ 10.99, 5.49, 3.00 ]) )
node node-app.mjs
Mode 2: --target wasm — Raw WASM
matchbox --target wasm my_lib.bxs
Use this when you need manual control over WASM loading, or integration with Webpack/Vite:
const { instance } = await WebAssembly.instantiateStreaming(
fetch('/my_lib.wasm'),
{}
)
const { greet } = instance.exports
Vite Integration
import { defineConfig } from 'vite'
export default defineConfig({
assetsInclude: ['**/*.wasm'],
plugins: []
})
import wasmUrl from './my_lib.wasm?url'
const response = await fetch(wasmUrl)
const { instance } = await WebAssembly.instantiateStreaming(response)
const { greet } = instance.exports
Function Export Rules
- All top-level functions are exported automatically (no
public annotation needed)
- Functions defined inside class bodies are NOT exported
- Keep exported BoxLang functions at the top level of the
.bxs file
function add( a, b ) {
return a + b
}
function formatCurrency( amount, currency = "USD" ) {
return currency & " " & numberFormat( amount, "2" )
}
class MyLib {
function helper() { ... }
}
Browser Compatibility
| Browser | ES Module WASM Support |
|---|
| Chrome 61+ | ✅ |
| Firefox 60+ | ✅ |
| Safari 14.1+ | ✅ |
| Edge 79+ | ✅ |
| Node.js 14+ | ✅ |
Bundler Integration
Webpack 5
module.exports = {
experiments: {
asyncWebAssembly: true
}
}
const myLib = await import('./my_lib.js')
myLib.greet("Webpack")
Vite + ES Module
import { greet } from '/my_lib.js'
greet("Vite")
Development Workflow
cat > utils.bxs << 'EOF'
function slugify( text ) {
return text.lCase().reReplace( "[^a-z0-9]+", "-", "all" ).trim( "-" )
}
function truncate( text, maxLen = 100 ) {
return text.len() > maxLen ? text.left( maxLen ) & "..." : text
}
EOF
matchbox --target js utils.bxs
npx serve .
Important: WASM files must be served over HTTP (not file://). Use a local dev server like npx serve, Vite, or a browser extension during development.
Checklist
