zig-javascript-bridge

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #android #machine-learning #deep-learning #nodejs #macos #awesome #kubernetes #awesome-list #mcp #open-source

zig-javascript-bridge

(★ 89)

Easily call Javascript from Zig wasm

zig-javascript-bridge 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# zig-javascript-bridge

This library creates bindings for accessing Javascript from within a WASM runtime.  For example:

```zig
const zjb = @import("zjb");

export fn main() void {
    zjb.global("console").call("log", .{zjb.constString("Hello from Zig")}, void);
}

```

Is equivalent to this Javascript:
```javascript
console.log("Hello from Zig");
```

## Project Status

ZJB is fully functional and is ready to be used in other projects.  However 1.0 will not be tagged until Zig is 1.0, and there is significant enough usage that confidence in the API not needing further changes is high.

## Why

Calling Javascript functions from Zig is a pain.  WASM has restrictions on the function API surface, and how references to the runtime environment (Javascript) can be stored.  So to access Javascript functionality from Zig, you must create: a function in Zig which is friendly to call, a function export, and a function in Javascript which translates into the call you actually want.

This isn't too bad so far, but the Javascript API surface is large, has a lot of variadic functions, and accepts many types.  The result is that your programming loop of just wanting to write code slows down writing a large amount of ill fitting boilerplate whenever you must cross the Zig to Javascript boundary.

This package is clearly inspired by Go's solution to this problem: https://pkg.go.dev/syscall/js  However, there are a few significant deviations to note if you're familiar with that library:

1. Every call from Go's package involves string decoding, garbage creation, and reflection calls.
2. Go has a one size fits all Javascript file, while zjb uses a generator to produce Javascript for the calls you use.
3. Go's garbage collection and finalizers allows for automatically cleaning up references from Go to Javascript, while zjb requires manual Handle releasing.
4. Zig has no runtime, so there's none of Go's weirdness about blocking on the main thread.

## Usage

As of 2026-04-16, zjb is only known to work with Zig 0.16.0.  If you're using an older version of Zig, look at past commits.  If you're looking for a newer version of Zig, check for branches.

The simple folder provides a good template to start from.  You'll need to update to reference to zjb in `build.zig.zon`.  There's currently no release schedule for point releases, so you should use the latest available code.  Eg, copy the entire `simple` folder into your empty project, then run `zig fetch --save=zjb git+https://github.com/scottredig/zig-javascript-bridge`

Call into Javascript using `zjb`, generate the Javascript side code, and then build an html page to combine them.

### Example

An example which demonstrates usage of all of the components of `zjb` is in the example folder.  It includes:

- `src/main.zig` has usage examples for the `zjb` Zig import.
- `build.zig`'s example for how to set up your build file.
- `static` includes HTML and Javascript files to run the example.

`zig build` from inside the example folder builds the example to `zig-out`.  As a webserver is required to view the samples in action, you can instead use `zig build serve` to build and host the example locally.

### Details

Zjb functions which return a value from Javascript require specifying which type is returned.  As arguments or return types to be passed into Javascript, zjb supports:

- `i32`, `i64`, `f32`, `f64`.  These are the only numerical types that are supported by the WebAssembly JavaScript Interface, so you must cast to one of these before passing.
- `comptime_int`, `comptime_float`.  These are valid as arguments, and are passed as f64 to Javascript, which is Javascript's main number type.
- `zjb.Handle`.  The Zig side type for referring to Javascript values.  Most of the time this will be a Javascript object of some kind, but in some rare cases it might be something else, such as null, a Number, NaN, or undefined.  Used as an argument, it is automatically converted into the value that is held in zjb's Javascript `_handles` map.  When used as a return value, it is automatically added to zjb's Javascript `_handles` map.  It is the caller's responsibility to call `release` to remove it from the `_handles` map when you're done using it.
- `zjb.ConstHandle` as arguments but not return types.  These values are returned by `zjb.constString`, `zjb.global`, and `zjb.fnHandle`.  `zjb.ConstHandle` works similarly to `zjb.Handle`, with a few notable exceptions: 1. Values are memoized upon first use on the Zig side, so they can be used any number of times without churning garbage.  2. There is no `release` function.  These values are intended to be around for the lifetime of your program, with reduced friction of using them.  As the functions which produce ConstHandle values all take only comptime arguments, these cannot balloon uncontrolably at runtime.  Some values are always defined as handles, `zjb.ConstHandle.null` is Javascript's `null`, `zjb.ConstHandle.global` is the global scope, and `zjb.ConstHandle.empty_string` is a Javascript empty string.
- `void` is a valid type for method calls which have no return value.

Zjb supports multiple ways to expose Zig functions to Javascript:
- `zjb.exportFn` exposes the function with the passed name to Javascript.  This supports `zjb.Handle`, so if you pass an object from a Javascript function, a handle will automatically be created and passed into Zig.  It is the responsibility of the Zig function being called to call `release` on any handles in its arguments at the appropriate time to avoid memory leaks.
- `zjb.fnHandle` uses `zjb.exportFn` and additionally returns a `zjb.ConstHandle` to that function.  This can be used as a callback argument in Javascript functions.
- Zig's `export` keyword on functions works as it always does in WASM, but doesn't support `zjb.Handle` correctly.

Simple Zig global variables can also be exposed to Javascript:
- `zjb.exportGlobal` exposes the variable with the passed address to Javascript. This supports `bool`, `i32`, `i64`, `u32`, `u64`, `f32`, and `f64`. Property descriptors will be created with get/set methods that provide access to the variable.

A few extra notes:

`zjb.string([]const u8)` decodes the slice of memory as a utf-8 string, returning a Handle.  The string will NOT update to reflect changes in the slice in Zig.

`zjb.global` will be set to the value of that global variable the first time it is called.  As it is intended to be used for Javascript objects or classes defined in the global scope, that usage will be safe.  For example, `console`, `document` or `Map`.  If you use it to retrieve a value or object you've defined in Javascript, ensure it's defined before your program runs and doesn't change.

The \_ArrayView functions (`i8ArrayView`, `u8ArrayView`, etc) create the respective JavaScript typed array backed by the same memory as the Zig WASM instance.

`dataView` is similar in functionality to the ArrayView functions, but returns a DataView object.  Accepts any pointer or slice.

The generated Javascript also includes a shortcut function named `dataView` to get an up-to-date cached `DataView` of the entire WebAssembly `Memory`.

> [!CAUTION]
> There are three important notes about using the \_ArrayView and dataView functions:
>
> The \_ArrayView and dataView functions will accept const values.  If you pass one (such as []const u8), you are exposing Zig's memory to Javascript.  Changing the values from Javascript may lead to undefined behavior.  Zjb allows this as there are plenty of use cases which only read the data, and requiring non-const values throughout your program if they are eventually passed to Javascript isn't a desirable API.  It's up to you to be safe here.
>
> Changes to the values in either Zig or Javascript will be visible in the other.  HOWEVER, if the wasm memory grows for whatever reason (either through a direct @wasmMemoryGrow call or through allocators), all \_ArrayViews and DataViews are invalided, and their length will be zero.  You have (roughly speaking) three choices to handle this:
> 1. Always create just before using, and release immediately after use.
> 1. Never allocate after using these functions.
> 1. Check their length before any use, if it does not match the intended length, release and recreate the Handle.
>
> Javascripts's DataView allows pulling out arbitrary values from offsets.  This may be useful for working with Zig structs from Javascript, however remember that Zig may reorder the fields for structs.  Use `extern struct` to be safe here.

## How

To solve the general problem of referencing Javascript objects from Zig, an object on the Javascript side with integer indices is used.  When passing to Javascript, the object is added to the map with a unique ID, and that ID is passed to Zig.  When calling from Zig, Javascript will translate the ID into the object stored on the map before calling the intended function.  To avoid building up garbage endlessly inside the object map, zjb code must call release to delete the reference from the map.

zjb works with two steps:

1. Your Zig code calls zjb functions.  Many functions use comptime to create export functions with specialized export signatures.  Only methods which are actually used are in the final WASM file.
2. Run an extract methods program on the WASM file, producing a Javascript file to use along with your WASM file.  The example above produces this export, for example:

```javascript
const Zjb = class {
  new_handle(value) {
    if (value === null) {
      return 0;
    }
    const result = this._next_handle;
    this._handles.set(result, value);
    this._next_handle++;
    return result;
  }
  dataView() {
    if (this._cached_data_view.buffer.byteLength !== this.instance.exports.memory.buffer.byteLength) {
      this._cached_data_view = new DataView(this.instance.exports.memory.buffer);
    }
    return this._cached_data_view;
  }
  constructor() {
    this._decoder = new TextDecoder();
    this.imports = {
      "call_o_v_log": (arg0, id) => {
        this._handles.get(id).log(this._handles.get(arg0));
      },
      "get_o_console": (id) => {
        return this.new_handle(this._handles.get(id).console);
      },
      "string": (ptr, len) => {
        return this.new_handle(this._decoder.decode(new Uint8Array(this.instance.exports.memory.buffer, ptr, len)));
      },
    };
    this.exports = {
    };
    this.instance = null;
    this._cached_data_view = null;
    this._export_reverse_handles = {};
    this._handles = new Map();
    this._handles.set(0, null);
    this._handles.set(1, window);
    this._handles.set(2, "");
    this._handles.set(3, this.exports);
    this._next_handle = 4;
  }
  setInstance(instance) {
    this.instance = instance;
    const initialView = new DataView(instance.exports.memory.buffer);
    this._cached_data_view = initialView;
  }
};

```

zig-javascript-bridge

zig-javascript-bridge 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

zig-javascript-bridge

zig-javascript-bridge 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README