Webassembly on despatches

Using `locateFile` to have js and wasm in different locations with emscripten

Thu, 18 Sep 2025 10:15:42 +0100

As part of building shine, I am using lume and webassembly with zig.

zig, through emscripten generates both a js and wasm file, which, by default are expected to be in the same directory.

I wanted to put them in different places, and struggled to get that working with lume for a bit. I did eventually solve it though:

Include emscripten js file

Firstly, the js file output from emscripten should be included in you page manually. I had used site.add which meant that it was loaded before we could put the override for locateFile in window.Module.

I am using the simple-blog theme, so I add the following line to the top of src/index.vto

```html ```

Override `Module`

You can override how emscripten finds the wasm file in the Module Object.

This can be done in the html file in a script block, or even better, in a js file that is included automatically.

js/main.js felt like a good place.

```javascript window.Module = { locateFile: function (path, scriptDirectory) { if (path === "shine.wasm") { return "/static/shine/shine.wasm"; } else { return scriptDirectory + path; } }, }; ```

Closing

With this setup, I can not only have the js and wasm files in different locations, it’s also easy to modify / augment the Module object.

Calling Javascript from Zig through WebAssembly

Wed, 17 Sep 2025 15:52:20 +0100

The next step for shine is to build a bridge between zig and javascript.

I am currently planning to using supabase for storage. Unsurprisingly, it does not have a zig sdk. It does, however, have a javascript sdk.

If I can write basic CRUD operations in javascript and call that from zig through webassembly, that could make that integration a lot easier.

Goals

There are a few ideal restrictions for me - mainly because writing javascript is not fun for me.

Use the Supabase js/ts library through zig
Use TypeScript as much as possible. (I don’t love TypeScript, but at least it’s not javascript)
Keep as much of the supabase related code in the web part so that deno and lume can handle any heavy lifting.

Options

I can’t use FFI(Foreign Function Interface):

```zig extern "env" fn jsLog(ptr: [*]const u8, len: usize) void; ``` ```javascript const wasm = await WebAssembly.instantiateStreaming(fetch("prog.wasm"), { env: { jsLog: (ptr, len) => { /* read from memory and console.log */ }, }, }); ```

because imgui pulls in emscripten, which means we don’t have the ability to call instantiateStreaming.

With emscripten, declaring an external function is easy enough.

```zig extern fn jsLog(ptr: [*]const u8, len: usize) void; ```

There are a couple of options to wire them up to the javascript:

`library.js` / `mergeInto`

This option requires javascript files on the zig side. If you want to start with typescript, you’ll need to integrate a transpiler into the build chain as well.

First, you want a javascript file - let’s call it libshine.js, and pop it into a js dir.

```javascript // js/libshine.js // Emscripten will provide these globals at link/runtime declare var mergeInto: (lib: any, funcs: Record) => void; declare var LibraryManager: { library: any }; declare function UTF8ToString(ptr: number, len?: number): string; mergeInto(LibraryManager.library, { jsLog: (ptr: number) => { const msg = UTF8ToString(ptr); console.log("🟢 Zig says:", msg); }, }); ```

We then need to pass this js file into the build step

as part of my sokol build step, I pass it in as .extra_args.

```zig // create a build step which invokes the Emscripten linker const link_step = try sokol.emLinkStep(b, .{ .lib_main = shine, .target = opts.mod_main.resolved_target.?, .optimize = opts.mod_main.optimize.?, .emsdk = dep_emsdk, .use_webgl2 = true, .use_emmalloc = true, .use_filesystem = false, .shell_file_path = opts.dep_sokol.path("src/sokol/web/shell.html"), // set the js file here .extra_args = &.{ "--js-library", "js/libshine.js", }, }); ```

We can then call it from zig, with something like:

```zig pub fn main() void { jsLog("hello from zig"); } extern fn jsLog(ptr: [*]const u8) void; ```

From my firefox console:

``` Lume live reloading is ready. Listening for changes... localhost:3000:102:15 🟢 Zig says: hello from zig shine.js:3168:11 ```

`EM_JS` / `EM_ASM`

The other option is to use EM_JS which involves writing a wee bit of C, which can embed the javascript.

In theory, it’s as simple as:

```c #include EM_JS_DEPS(bla, "$UTF8ToString"); EM_JS(void, jsLog, (const char* s), { console.log(UTF8ToString(s)); }); ```

and adding it into the build file:

```zig // build the main file into a library, this is because the WASM 'exe' // needs to be linked in a separate build step with the Emscripten linker const shine = b.addLibrary(.{ .name = "shine", .root_module = opts.mod_main, }); // get the Emscripten SDK dependency from the sokol dependency const dep_emsdk = opts.dep_sokol.builder.dependency("emsdk", .{}); // need to inject the Emscripten system header include path into // the cimgui C library otherwise the C/C++ code won't find // C stdlib headers const emsdk_incl_path = dep_emsdk.path("upstream/emscripten/cache/sysroot/include"); shine.root_module.addCSourceFile(.{ .file = b.path("src/libjs.c"), .flags = &.{}, // optional extra emcc flags }); shine.addSystemIncludePath(emsdk_incl_path); ```

The calling code in main.zig remains the same:

```zig pub fn main() void { jsLog("hello from zig"); } extern fn jsLog(ptr: [*]const u8) void; ```

However, this didn’t work, and failed with:

``` error: undefined symbol: jsLog (referenced by root reference (e.g. compiled C/C++ code)) warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0` warning: _jsLog may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library Error: Aborting compilation due to previous errors ```

Thanks to some help from flooh (who btw put together the sokol and sokol-zig packages as well the sokol-imgui-sample template which I used to kick start this project.), I was able to get it working.

Turns out the c file needs to have a function in it that is used in the zig file - it doesn’t need to do anything.

So, based on the suggestion, libjs.c changes to:

```c #include EM_JS_DEPS(bla, "$UTF8ToString"); EM_JS(void, jsLog, (const char* s), { console.log(UTF8ToString(s)); }); void dummy(void) {}; ```

and in main.zig:

```zig pub fn main() void { dummy(); jsLog("hello from zig"); } extern fn jsLog(ptr: [*]const u8) void; extern fn dummy() void; ```

From my firefox console:

``` Lume live reloading is ready. Listening for changes... localhost:3000:102:15 🟢 Zig says: hello from zig shine.js:3168:11 ```

You can see a working example in [my forked repo](

`EM_JS` directly through `zig` [unsuccessful]

Looking at the macro for EM_JS and with my good friend ChatGPT, I attempted translating it to zig and made some progress, but ultimately failed to get it working. I’ll leave the work here in the hopes it might be helpful.

```c #define _EM_JS(ret, c_name, js_name, params, code) \ _EM_BEGIN_CDECL \ ret c_name params EM_IMPORT(js_name); \ __attribute__((visibility("hidden"))) \ void* __em_js_ref_##c_name = (void*)&c_name; \ EMSCRIPTEN_KEEPALIVE \ __attribute__((section("em_js"), aligned(1))) char __em_js__##js_name[] = \ #params "<::>" code; \ _EM_END_CDECL ```

The above macro translates to zig roughly (with help from ChatGPT) as:

```zig extern fn jsLog(ptr: [*]const u8) void; /// 2. Keep a reference to avoid the linker removing the function. /// Same role as __em_js_ref_* in the C macro. pub export const __em_js_ref_jsLog = &jsLog; /// 3. Embed the JS implementation in a special section called "em_js". /// Emscripten will scan this and inject the code into the output JS. export const __em_js__jsLog align(1) linksection("em_js") = "(const char* s)<::>{ console.log(UTF8ToString(s)); }\x00"; pub export fn dummy() void {} ```

I added a pub fn and called it from main:

```zig pub fn log(ptr: [*]const u8) void { jsLog(ptr); } ```

Which gave me the familiar error about not being able to find jsLog.

comparing the linker sections gave some clues:

``` ❯ wasm-objdump --section=linking -x libjs.o: file format wasm 0x1 Section Details: Custom: - name: "linking" - symbol table [count=9] - 0: F func=1 [ binding=global vis=hidden ] - 1: D <__em_js_ref_jsLog> segment=0 offset=0 size=4 [ binding=global vis=hidden ] - 2: F func=0 [ undefined explicit_name binding=global vis=default ] - 3: D <__em_js__jsLog> segment=1 offset=0 size=53 [ exported no_strip binding=global vis=hidden ] - 4: S <.debug_abbrev> section=7 [ binding=local vis=default ] - 5: G global=0 [ undefined binding=global vis=default ] - 6: S <.debug_str> section=9 [ binding=local vis=default ] - 7: T table=0 [ undefined exported no_strip binding=global vis=default ] - 8: S <.debug_line> section=10 [ binding=local vis=default ] - segment info [count=2] - 0: .data.__em_js_ref_jsLog p2align=2 [ ] - 1: em_js p2align=0 [ RETAIN ] ```

and the zig object:

``` ❯ wasm-objdump --section=linking -x js.o js.o: file format wasm 0x1 Section Details: Custom: - name: "linking" - symbol table [count=6] - 0: F func=1 [ binding=global vis=default ] - 1: D <__em_js_ref_jsLog> segment=0 offset=0 size=4 [ binding=global vis=default ] - 2: F func=0 [ undefined explicit_name binding=global vis=default ] - 3: D <__em_js__jsLog> segment=1 offset=0 size=4 [ binding=global vis=default ] - 4: D <__anon_946> segment=2 offset=0 size=54 [ binding=local vis=default ] - 5: T table=0 [ undefined exported no_strip binding=global vis=default ] - segment info [count=3] - 0: .rodata.__em_js_ref_jsLog p2align=2 [ ] - 1: em_js p2align=0 [ ] - 2: .rodata.__anon_946 p2align=0 [ ]` ```

From what I could understand (which is little), it looks like __em_js__jsLog in the zig obj is a pointer while from C, it’s the full string.

hardcoding it as a static array helped:

```zig export const __em_js__jsLog align(1) linksection("em_js") = [_]u8{ '(', 'c','o','n','s','t',' ','c','h','a','r','*',' ','s',')', '<',':',':','>','{',' ', 'c','o','n','s','o','l','e','.','l','o','g','(', 'U','T','F','8','T','o','S','t','r','i','n','g','(', 's',')',')',';',' ','}','\x00', }; ```

The output from this is a little more promising

``` ❯ wasm-objdump --section=linking -x js.o js.o: file format wasm 0x1 Section Details: Custom: - name: "linking" - symbol table [count=5] - 0: F func=1 [ binding=global vis=default ] - 1: D <__em_js_ref_jsLog> segment=0 offset=0 size=4 [ binding=global vis=default ] - 2: F func=0 [ undefined explicit_name binding=global vis=default ] - 3: D <__em_js__jsLog> segment=1 offset=0 size=53 [ binding=global vis=default ] - 4: T table=0 [ undefined exported no_strip binding=global vis=default ] - segment info [count=2] - 0: .rodata.__em_js_ref_jsLog p2align=2 [ ] - 1: em_js p2align=0 [ ] ```

Let’s look at the two side by side

``` # From C - 3: D <__em_js__jsLog> segment=1 offset=0 size=53 [ exported no_strip binding=global vis=hidden ] # From zig - 3: D <__em_js__jsLog> segment=1 offset=0 size=53 [ binding=global vis=default ] ```

There are some clear differences in how the two are output and I am already beyond my knowledge level here - so I’ll leave it to someone who knows this stuff better (or wait until I do)

You can check out the code in the branch of my forked repo

Next steps

My plan is to use EM_JS through C to implement glue JavaScript functions - something like:

```c EM_JS(void, jsLog, (const char* s), { Module.jsLog(UTF8ToString(s)); }); ```

By doing this, I can have one-line js code in the .c file and all the implementation can go into the web side (and can easily be TypeScript too).

```javascript window.Module = { jsLog: function (msg) { console.log("🟢 Zig says:", msg); }, }; ```

Auto reload WASM with zig+lume

Tue, 16 Sep 2025 15:56:42 +0100

I’ve been taking some time off to rest and recover from health issues that made it hard to focus. To ease back in, I’ve started a small project: shine

The project would do well to be multiplatform - mobile and web. The obvious choice was flutter and I have enjoyed working with it before.

However, as I’m currently in love with zig, I wanted to work with that instead.

Libraries

Graphics

I’ve been playing with raylib and that was my initial instinct. However, raylib does not support iOs and has issues with wasm

I considered a few options, including

sdl, which looked great but was perhaps a little too low level for me.
jok - does not support mobile and possibly has a little more than I needed.

In the end, I decided to go with sokol and sokol-zig.

While a little more lower level than raylib, it has:

a modern clean api
first class mobile support
first class wasm support

UI

I’ve been working with dvui a lot recently. Unfortunately, it doesn’t support sokol. imgui is a better option.

There is even a template project that I could start from.

WASM first

To keep things straightforward, I decided to start with wasm. If I make the site mobile friendly, I could see how it goes and see if it needs a mobile version.

I will need some shared data storage and have been considering supabase, which has javascript libs. By using wasm, I can effectively shim in js functions to handle that instead of having to write bare rest calls from zig.

Structuring the project

Is this a zig project with a web component, vice versa or indeed two independent parts that work together.

I did a fair amount of web searching to see if there was some guidance I could I find for a good way to structure a relatively straightforward zig+js project.

I could not find one. In the end, I decided to keep it fairly straightforward.

``` - shine/ - src/ # zig code - web/ # all the web stuff ```

Frontend

After a bit of research, and realising that I will probably need a little bit of supporting content around shine, I decided to go with lume

I used the simple-blog theme as a template to start from. I could have just pulled the template in but I wanted a custom homepage.

When I tried to add an index.md, it complained about two files wanting to write index.html. From what I could find, the easiest way to override the homepage was to just pick up the theme and edit it - which was easy enough.

WASM => frontend

I didn’t want to copy over the wasm and the js file every time, so I added a couple of steps to build.zig right after the link_step (also included below)

```zig // build.zig // create a build step which invokes the Emscripten linker const link_step = try sokol.emLinkStep(b, .{ .lib_main = shine, .target = opts.mod_main.resolved_target.?, .optimize = opts.mod_main.optimize.?, .emsdk = dep_emsdk, .use_webgl2 = true, .use_emmalloc = true, .use_filesystem = false, .shell_file_path = opts.dep_sokol.path("src/sokol/web/shell.html"), }); // attach to default target b.getInstallStep().dependOn(&link_step.step); // Copy shine.js from default emscripten output const js_install = b.addInstallFileWithDir( b.path("zig-out/web/shine.js"), .{ .custom = "../web/src/static/shine" }, "shine.js", ); js_install.step.dependOn(&link_step.step); b.getInstallStep().dependOn(&js_install.step); // Copy shine.wasm from default emscripten output const wasm_install = b.addInstallFileWithDir( b.path("zig-out/web/shine.wasm"), .{ .custom = "../web/src/static/shine" }, "shine.wasm", ); wasm_install.step.dependOn(&link_step.step); ```

These steps will copy across the wasm and the js file across to static/shine. I wanted to put the js in src/js and the wasm in the static dir. However, the js file expects the wasm in the same dir. ~~I tried overriding locateFile but it didn’t work.~~(you can use a different location by overriding locateFile)

```html ```

I was able to get lume to process the javascript file by adding it.

```javascript // _config.ts site.add("static/shine/shine.js"); ```

Conclusion

With all of these set up, I was able to run:

```bash zig build -Dtarget=wasm32-emscripten --watch ``` ``` ```

in one window. This command will rebuild wasm and provide it to lume whenever the zig code changes.

```bash deno task serve ```

Running this in another window will mean that lume will rebuild on any changes, including a new wasm file and redeploy. The redeploy will trigger an auto-reload of the page as well if I have it in a browser.

I now effectively have automated reload with changes if I make changes in either zig or the frontend.

I don’t have hot reload - but this is pretty good for now.