Moonbit JS Binding

MoonBit JS Binding Guide

Step-by-step workflow for binding JavaScript APIs (browser DOM, Node built-ins, npm packages) to MoonBit through the js backend.

When To Use

Use this skill when:

• Adding extern "js" fn declarations for a JS API
• Embedding inline JS (#| (x) => ...) or importing by module+name (= "Math" "max")
• Configuring moon.pkg with link.js exports and format: esm/cjs/iife
• Wrapping JS objects with #external pub type and %identity casts
• Bridging Promises with async fn + %async.suspend + %async.run
• Mapping undefined / null distinctly into MoonBit Option
• Consuming npm packages via require(...) or ESM imports
• Generating .d.ts for TypeScript consumers

Plan Mode Instructions

If you are in plan mode and creating a plan for moonbit-js-binding work:

1. In your final plan file, include an explicit instruction at the beginning that tells the executing agent to read the moonbit-js-binding skill before starting implementation.
2. The instruction should look like this:

   **Before starting implementation:** Use the Skill tool to load the moonbit-js-binding skill, which provides comprehensive guidance on `extern "js"` declarations, JS value wrapping, Promise bridging, and moon.pkg export configuration.
   

Type Mapping

Map JS types to MoonBit types before writing any declarations.

Warning — Number precision: JavaScript has no integer type. Values crossing the FFI boundary round to IEEE-754 doubles. Int is fine for \|x\| < 2^53; beyond that use BigInt. UInt64 / Int64 currently map through JS number and lose bits above 2^53.

Warning — Trait objects & MoonBit enums: Passing Map[K, V], Result[_], Json, or non-#external trait objects across FFI exposes MoonBit's internal runtime shape. Convert to plain structs, JsValue, or primitives first.

Workflow

Follow these 4 phases in order.

Phase 1: Project Setup

Configure the module and package for JS output.

Module (moon.mod.json) — set preferred-target so moon check, moon build, moon test default to js:

{
  "name": "user/pkg",
  "version": "0.1.0",
  "source": "src",
  "preferred-target": "js"
}

Package (src/moon.pkg) — gate .mbt files to the js backend and configure link output.

File format — moon.pkg (DSL) vs moon.pkg.json (JSON): MoonBit accepts either filename. This skill uses the DSL form moon.pkg (no extension) throughout. Do NOT write moon.pkg.json; it is a different syntax (pure JSON, no options(...) wrapper, no trailing commas). Mixing them mid-project causes "Unable to read moon.pkg" parse errors. If you cloned an older template using .pkg.json, delete it and use moon.pkg as shown below.

targets: — only needed for backend-specific files: The targets: block gates individual .mbt files to a subset of backends. Files that contain extern "js", extern "c", or backend-specific #cfg blocks must be listed. Pure MoonBit files (no FFI) do NOT need a targets: entry — if every file in the package is pure MoonBit, omit the targets: block entirely. The example above lists ffi.mbt / async.mbt because they contain extern "js"; a simple library with no FFI only needs link: { ... }.

import {
  "moonbitlang/async",
} for "test"

options(
  targets: {
    "ffi.mbt": ["js"],
    "async.mbt": ["js"],
    "async_test.mbt": ["js"],
  },
  link: {
    "js": {
      "exports": ["add", "greet"],
      "format": "esm",
    },
  },
)

Key fields:

Warning — supported-targets vs targets: Do NOT use supported-targets: ["js"] at the package level. It blocks downstream consumers. Gate individual files with targets instead.

Warning — preferred-target: "js": This is a default, not a lock. moon test --target wasm-gc still works on files that support it — useful for cross-backend libraries.

Two ways to gate code by backend — targets: (file-level) vs #cfg() (declaration-level):

Conditions you will see inside #cfg(...):

#cfg(target="js")                          // JS only
#cfg(target="native")                      // native only
#cfg(not(target="js"))                     // everything except JS
#cfg(any(target="wasm", target="wasm-gc")) // either wasm backend
#cfg(any(target="native", target="llvm"))  // either non-GC backend
#cfg(false)                                // always exclude (quick disable)

moonbitlang/core uses this pattern extensively — e.g. Int16::from_int64 has a %i64_to_i16 intrinsic on native/wasm but a fallback implementation on JS where 64-bit integers don't have a native representation:

///|
#cfg(not(target="js"))
pub fn Int16::from_int64(self : Int64) -> Int16 = "%i64_to_i16"

///|
#cfg(target="js")
pub fn Int16::from_int64(self : Int64) -> Int16 {
  Int16::from_int(self.to_int())
}

The same file-level rule applies to #cfg: every target your function is callable from must have exactly one matching definition. Overlapping #cfg guards are a compile error. #cfg(target="js") + #cfg(not(target="js")) cover everything; #cfg(target="js") alone on a non-intrinsic declaration means that function does not exist on other backends and any code that calls it must itself be #cfg-gated (or live in a file gated via targets:).

Choosing between them: If the whole file is extern "js" wrappers, gate the file via targets: — simpler, and moon check --target wasm-gc skips the file entirely. If you are writing a cross-backend library where 90% of the logic is shared and only a few functions differ, reach for #cfg.

Phase 2: FFI Layer

Write extern "js" declarations. Keep them private (or prefixed ffi_); expose safe wrappers in Phase 3.

Inline JS (#| literal):

///|
extern "js" fn ffi_console_log(msg : String) -> Unit =
  #| (msg) => console.log(msg)

///|
extern "js" fn ffi_sqrt(x : Double) -> Double =
  #| (x) => Math.sqrt(x)

The #| literal is the function body as raw JS source. The MoonBit compiler inlines it at the call site — no closure allocation at runtime.

Module-and-name form (imports an existing JS function directly):

///|
extern "js" fn math_max(a : Double, b : Double) -> Double = "Math" "max"

Use this when you want to reference a globally accessible function without wrapping it in a closure. Slightly faster and smaller.

#module("pkg") — compile-time ESM / CJS import:

For named exports from JS modules (Node built-ins, npm packages, local .js files), annotate the extern "js" with #module("module-id"). The right-hand side is the export name inside that module (not an inline JS body):

///|
#module("node:path")
extern "js" fn path_basename(p : String) -> String = "basename"

///|
#module("node:path")
extern "js" fn path_extname(p : String) -> String = "extname"

What the compiler emits:

Why #module() beats a hand-rolled require("...") wrapper:

• Statically analyzable. Vite / esbuild / Rollup can trace the dependency, tree-shake, and resolve paths correctly.
• Format-agnostic source. The same .mbt file works under ESM (where require isn't defined) and CJS without a second code path.
• Smaller generated code. No per-call closure; the destructured local is reused.
• Bundler-compatible paths. Works for npm package specifiers ("lodash"), Node built-ins ("node:path"), relative files ("./helpers.js"), and URL-style specifiers when supported by the runtime.

Constraints:

1. Named exports only. The RHS must be a key exported from the module. For default exports or modules whose top-level value is the function itself, you need a bridge re-export on the JS side, or fall back to inline import/require in an FFI body.
2. One export per declaration. You cannot share a destructure across multiple #module FFIs — each annotation generates its own import line. The compiler deduplicates the module specifier, so you pay one require per unique module, not per function.
3. Module-name literal must be compile-time constant. Dynamic module paths (#module(some_variable)) are not supported. For dynamically chosen modules, fall back to require(name) in inline JS.
4. No inline body allowed. #module("pkg") + extern "js" fn f() = "name" is the only shape. Mixing with #| (...) => ... is a compile error.
5. Browser globals don't need it. For window, document, fetch, Math, etc., use inline JS or the module+name form (= "Math" "max"); they are not imported, just accessed.
6. Side-effectful imports are still side-effectful. The import/require fires when the compiled module loads. If pkg has top-level side effects (CLI banners, global patching), they run during import even if you never call the FFI function.
7. Test vs release format. moon test uses CJS harness regardless of your link.js.format. If a module is ESM-only (no CJS entry point in package.json exports), its tests may fail even though moon build --release works. Gate those tests or use a dual-format package.

When to use which form:

Multi-line inline JS:

///|
extern "js" fn ffi_do_work(x : Int) -> Int =
  #| (x) => {
  #|   const y = x * 2;
  #|   return y + 1;
  #| }

Opaque JS value pattern:

For anything without a MoonBit equivalent (DOM nodes, npm objects, undefined, null), wrap it in #external pub type:

///|
#external
pub type JsValue

///|
/// Zero-cost bitcast — compiles to nothing.
pub fn[A, B] identity(a : A) -> B = "%identity"

%identity is a compiler intrinsic: it moves a value across types at the type-checker level and emits no JS code. Use it to lift primitives into JsValue and back. It is unchecked at runtime — wrong use is a silent type error.

Generic FFI operations on JsValue:

///|
pub extern "js" fn JsValue::get(self : JsValue, key : String) -> JsValue =
  #| (obj, key) => obj[key]

///|
pub extern "js" fn JsValue::set(
  self : JsValue,
  key : String,
  value : JsValue,
) -> Unit =
  #| (obj, key, value) => { obj[key] = value }

///|
pub extern "js" fn JsValue::call_method(
  self : JsValue,
  name : String,
  args : Array[JsValue],
) -> JsValue =
  #| (obj, name, args) => obj[name](...args)

These three primitives ( get / set / call_method ) can express virtually any JS object interaction.

Null / undefined distinction:

MoonBit T? cannot represent T | null | undefined safely — you'd get Some(null). Check explicitly with is_undefined / is_null:

///|
pub extern "js" fn is_undefined(v : JsValue) -> Bool =
  #| (v) => v === undefined

///|
pub fn[T] js_get_opt(obj : JsValue, key : String) -> T? {
  let v = obj.get(key)
  if is_undefined(v) {
    None
  } else {
    Some(identity(v))
  }
}

For libraries that distinguish null from undefined (e.g. FileReader.error), introduce Nullable[T] and Nullish[T] wrapper types and narrow with explicit checks.

Phase 3: MoonBit API

Build safe, typed, pub wrappers over the raw ffi_* externs.

///|
pub fn console_log(msg : String) -> Unit {
  ffi_console_log(msg)
}

///|
pub fn sqrt(x : Double) -> Double {
  if x < 0 { panic() }
  ffi_sqrt(x)
}

Exports to JS consumers:

Anything listed in moon.pkg link.js.exports must be pub. The compiler emits a named ESM export (or CJS property, or IIFE global) for each. A .d.ts is generated automatically from the public signature.

Phase 4: Promise / Async Bridging

MoonBit async uses two compiler intrinsics that translate to JS Promise internals:

Canonical setup (see references/promise-bridging.md for full detail). Declare in this order — each item depends on the previous:

///|
#external
pub type Promise[T]

///|
/// Cast Promise[T] to JsValue so JsValue methods (get/call_method) apply.
/// Required by `Promise::wait` below.
pub fn[T] Promise::to_any(self : Promise[T]) -> JsValue = "%identity"

///|
pub async fn[T, E : Error] suspend(
  f : ((T) -> Unit, (E) -> Unit) -> Unit,
) -> T raise E = "%async.suspend"

///|
pub fn run_async(f : async () -> Unit noraise) -> Unit = "%async.run"

///|
/// The bridge. `await promise` in JS = `promise.wait()` in MoonBit.
pub async fn[T] Promise::wait(self : Promise[T]) -> T {
  suspend(fn(ok, err) {
    self.to_any().call_method("then", [identity(fn(v : JsValue) { ok(identity(v)) })])
        .call_method("catch", [identity(fn(e : JsValue) { err(identity(e)) })])
    |> ignore
  })
}

When do you need %async.run vs just %async.suspend?

In short: async test users never write run_async. It is needed only when %identity-casting async computations into JS Promise land from a sync context.

Standard pattern — FFI returning Promise + async wrapper:

///|
extern "js" fn ffi_fetch_text(url : String) -> Promise[String] =
  #| (url) => fetch(url).then(r => r.text())

///|
pub async fn fetch_text(url : String) -> String {
  ffi_fetch_text(url).wait()
}

Callers write let body = fetch_text(url) inside an async test or async fn — no .wait() needed at the call site. Tests:

async test "fetch_text resolves" {
  let body = fetch_text("https://example.com")
  inspect(body.length() > 0, content="true")
}

Note — moonbitlang/async: async test blocks require import { "moonbitlang/async" } for "test" in moon.pkg. The dependency is only needed at test time. Add with moon add moonbitlang/async — version 0.17.0 or later is required (older 0.1.x releases don't support the current %async.suspend ABI). As of this skill's writing, 0.18.0 is known good.

Phase 5: Testing

moon check                           # type-check, fast
moon test                            # run all tests (js is default)
moon test src --filter "greet"       # filter by name
moon build                           # emit .js + .d.ts to _build/js/release/build/

Build output paths — debug vs release:

.d.ts is generated in both modes. For publishing to npm, use --release. For local experimentation, the default debug output is sufficient and links faster.

Running the generated module from Node:

# debug build
node --input-type=module -e 'import("./_build/js/debug/build/<pkg>.js").then(m => console.log(m.add(2,3)))'

# release build (after `moon build --release`)
node --input-type=module -e 'import("./_build/js/release/build/<pkg>.js").then(m => console.log(m.add(2,3)))'

A runnable end-to-end example lives under assets/js_binding_proj/ in this skill — see the directory for a minimal project with 8 passing tests (sync + async) that you can copy, adapt, and run with moon test.

Decision Table

Common Pitfalls

1. Forgetting to gate files with targets. A file containing extern "js" that isn't gated to ["js"] breaks moon check --target wasm-gc and native. Always gate FFI files.

2. Using T? to model T | null | undefined. MoonBit's None is not JS null, and Some(null) is a nonsense value. Split with is_undefined and is_null before lifting.

3. Relying on Int64 across FFI. JS number is IEEE-754 double. Any 64-bit integer > 2^53 silently rounds. Use BigInt or split into two Ints.

4. Exposing MoonBit internals by passing Map/Result/trait objects directly. These have a MoonBit-specific runtime layout. Convert to plain structs, Array[(K, V)], or JsValue at the boundary.

5. Missing moonbitlang/async for async test. The test-only import is easy to forget. Add import { "moonbitlang/async" } for "test" to moon.pkg before writing the first async test.

6. Forgetting %async.run when calling async from sync JS. Exported sync functions can't await. If you need to fire an async operation from a sync export, wrap it with run_async(async fn() noraise { ... }) and return a Promise explicitly.

7. Calling .wait() without being in an async context. .wait() is async — it only compiles inside an async fn or async test. Non-async callers need the Promise directly.

8. Using %identity where a real conversion is needed. %identity is a type-checker escape hatch with no runtime effect. Using it to cast Int ↔ String will produce a runtime error with no warning. Only use when the JS runtime representation genuinely matches.

9. Exporting a pub function that isn't in link.js.exports. It is callable from other MoonBit packages but not re-exported from the compiled JS module. Add the name to exports.

Example Project

A minimal, runnable project demonstrating every pattern above:

assets/js_binding_proj/
├── moon.mod.json           # preferred-target: js, moonbitlang/async dep
└── src/
    ├── moon.pkg            # targets + link.js.exports
    ├── ffi.mbt             # extern "js" + JsValue + inline JS
    ├── lib.mbt             # Safe public wrappers (add, greet, js_get_opt)
    ├── lib_test.mbt        # Sync tests
    ├── async.mbt           # Promise[T] + suspend + wait
    ├── async_test.mbt      # async test blocks
    ├── modules.mbt         # #module("node:path") ESM/CJS import demo
    ├── modules_test.mbt
    ├── cross_target.mbt    # #cfg(target="...") per-declaration gating demo
    └── cross_target_test.mbt

Run:

cd assets/js_binding_proj
moon test              # 12 tests pass (sync + async + #cfg + #module)
moon build             # emits ESM + .d.ts
node --input-type=module -e 'import("./_build/js/debug/build/js_binding_proj.js").then(m => console.log(m.add(2,3), m.greet("world"), m.basename("/a/b/c.html")))'
# → 5 Hello, world! c.html

References

@references/promise-bridging.md @references/interop-patterns.md @references/error-handling.md @references/typescript-integration.md @references/cfg-and-target-gating.md