nimbling

Nim to WebAssembly / JavaScript bindings — like wasm-bindgen for Nim

nimbling is a two-phase build-time and post-processing library that enables Nim code to call JavaScript functions and JavaScript code to call Nim functions through WebAssembly. It automatically generates JS glue code, TypeScript declarations, and manages the conversion of complex types (strings, objects, closures) between the two environments.

README на български

Nim had an old/experimental WASM backend that held the ecosystem back. The modern Nim compiler (>= 2.0) with a C backend can generate WASM via clang/emscripten, but there is no library for high-level JS interop. nimbling fills this gap.

Inspired by wasm-bindgen (Rust) — the architecture is adapted 1:1 for Nim.

import nimbling

proc greet(name: string): string {.wasmBindgen.} =
  result = "Hello, " & name & "!"

# Must be called once per module after all wasmBindgen procs
wasmBindgenFinalize()

The wasmBindgen macro at compile time:

1. Parse — analyzes the Nim AST of annotated procs
2. Codegen — generates {.exportc.} wrapper functions (converts ptr/len to/from Nim types)
3. Describe — generates __nbg_describe_* functions describing the types
4. Encode — serializes the Program descriptor to binary (varint LEB128)
5. Embed — embeds the data as a custom section __nimbling_unstable in the .wasm file

nimbling target.wasm --out-dir pkg/ --target bundler

The CLI reads the .wasm, extracts the custom section, decodes the Program descriptor, and generates:

• {name}.js — JavaScript glue module (heap management, import/export shims)
• {name}_bg.wasm — transformed Wasm module
• {name}.d.ts — TypeScript declarations

Since Wasm works only with numbers, JS objects are passed through a shared heap array:

JS object -> addHeapObject(obj) -> idx: u32 -> Nim: JsValue(idx: u32)

• Stack — temporary/borrowed references (push/pop for each function call)
• Slab — owned objects with dynamic lifetime (reference counting)

Generate Nim bindings directly from WebIDL at compile time:

import nimbling/runtime, nimbling/macroimpl_webidl

webidlBind("""
  interface Node {
    readonly attribute unsigned short nodeType;
    Node appendChild(Node newChild);
    static Document createDocument();
  };
  interface Document {
    Element getElementById(DOMString id);
  };
""")

# Now use: var n = Node(JsValue(idx: 0)); echo nodeType(n)

Generates type Node = distinct JsValue, attribute getters/setters, method calls — all with {.emit.} blocks following the same pattern as web_sys.nim.

The easiest way to use nimbling in a modern web project:

npm install --save-dev vite-plugin-nimbling

// vite.config.js
import { defineConfig } from 'vite';
import nimbling from 'vite-plugin-nimbling';

export default defineConfig({
  plugins: [nimbling({ target: 'web' })]
});

Then import .nim files directly:

import { greet, add } from './hello.nim';
await greet();

See js/vite-plugin-nimbling/ for full docs.

# Clone
git clone https://github.com/katehonz/nimbling.git
cd nimbling

# Run tests
nimble test

# Build CLI
nimble buildCli

# Use the CLI
./src/nimbling/cli input.wasm --out-dir pkg/ --target bundler

nimbling/
├── README.md                    # This file
├── README_BG.md                 # Bulgarian README
├── DESIGN.md                    # Architecture documentation (Bulgarian)
├── ROADMAP.md                   # Full roadmap with all tiers
├── LICENSE                      # MIT License
├── nimbling.nimble              # Nimble package manifest
├── docs/
│   ├── architecture.md          # Architecture deep-dive
│   ├── api.md                   # API reference
│   └── contributing.md          # Contribution guide
├── src/
│   ├── nimbling.nim             # Library entry point
│   └── nimbling/
│       ├── common.nim           # Shared types, constants, Program schema
│       ├── leb128.nim           # LEB128 encode/decode utilities
│       ├── encode.nim           # Binary encoder (varint LEB128)
│       ├── decode.nim           # Binary decoder
│       ├── describe.nim         # Type descriptor system
│       ├── runtime.nim          # JsValue, Closure, memory management
│       ├── macroimpl.nim        # {.wasmBindgen.} pragma macro
│       ├── macroimpl_closure.nim # Closure support
│       ├── macroimpl_async.nim  # Async/Promise support
│       ├── macroimpl_attrs.nim  # 11 wasmBindgen attributes
│       ├── macroimpl_webidl.nim # Compile-time WebIDL → Nim macro
│       ├── codegen.nim          # Type mapping & codegen helpers
│       ├── cli.nim              # CLI tool
│       ├── jsgen.nim            # JavaScript glue generator
│       ├── interp.nim           # Wasm stack-machine interpreter
│       ├── transforms.nim       # Wasm binary transforms
│       ├── js_sys.nim           # js-sys: 526 procs, 42 types, 40+ APIs
│       ├── web_sys.nim          # web-sys: ~472 procs, 27 Web APIs (hand-written)
│       ├── web_sys_generated.nim # web-sys: 4,734 procs, ~500+ APIs (auto-generated)
│       ├── webidl.nim           # WebIDL parser → Nim codegen
│       ├── wit.nim              # WIT adapter system
│       └── emscripten.nim       # Emscripten + Memory64 support
├── tests/
│   └── all.nim                  # Unit test suite (372 tests)
├── examples/
│   └── hello/                   # Hello World example
│       ├── hello.nim
│       ├── hello.nimble
│       └── panicoverride.nim
└── OLD/                         # Reference: wasm-bindgen (Rust) source

The NimLeptos framework uses nimbling for WebAssembly/JS interop in production-like applications. See the nimleptos/examples directory for:

The wasm_counter example is the most complete end-to-end demo. It shows:

• Reactive signals (createSignal, createMemo, createEffect) running in WASM
• Emscripten build with build.sh — compiles Nim → C → wasm via emcc
• EM_ASM DOM helpers — direct DOM manipulation from Nim through Emscripten macros
• JS ↔ WASM interop — exported procs (increment, decrement, render) called from HTML via Module.ccall
• Polished HTML demo (index.html) with CSS animations and reactive hot-state

cd nimleptos/examples/wasm_counter
./build.sh        # Requires Emscripten SDK
firefox index.html

MIT

Built with Nim and AI assistance