# How to Export gdext-nim Extensions to WebAssembly Using Emscripten

> Export gdext nim extensions to WebAssembly efficiently. Configure Emscripten, compile with gdextwiz, and enable Godot HTML5 export settings for a seamless web integration.

- Repository: [godot-nim 4+/gdext-nim](https://github.com/godot-nim/gdext-nim)
- Tags: how-to-guide
- Published: 2026-03-02

---

**To export gdext-nim extensions to WebAssembly, configure your `config.nims` with Emscripten toolchain settings including `-s SIDE_MODULE=1`, compile with `gdextwiz build -d:platform=web`, and enable Extensions Support and Thread Support in the Godot HTML5 export preset.**

The godot-nim/gdext-nim framework allows you to write Godot 4 extensions in Nim, but exporting these extensions to the web requires specific Emscripten configuration to produce WebAssembly side-modules. When targeting the web platform, gdext-nim compiles your Nim code to C, then uses Emscripten (`emcc`) to generate a Wasm side-module that Godot loads at runtime alongside the HTML5 engine build.

## Prerequisites: Installing Emscripten

Follow the official Emscripten download guide to install the toolchain. Ensure the `emcc` command is available on your system `PATH` and that the `EMSDK` environment variables are properly exported. gdext-nim relies on these tools being accessible when the `platform = web` build setting is detected.

## Configuring the WebAssembly Toolchain

In your project root, create or modify `config.nims` to inject Emscripten-specific flags. According to the building-and-exporting guide in [`docs/building-and-exporting-guide.md`](https://github.com/godot-nim/gdext-nim/blob/main/docs/building-and-exporting-guide.md) (lines 71-85), you must configure the Nim compiler to use `emcc` as both the compiler and linker when targeting the web platform.

Example `config.nims`:

```nim

# config.nims

import gdext/buildconf

let setting = BuildSettings(
  name: "MyExtension",
  extpath: projectDir() & "/myextension.gdextension",
  updateMethod: inject
)

configure(setting):
  case setting.platform
  of web:
    --cpu: wasm32
    --cc: clang
    when buildOS == "windows":
      --clang.exe: emcc.bat
      --clang.linkerexe: emcc.bat
    else:
      --clang.exe: emcc
      --clang.linkerexe: emcc

    # Required side-module flags for Godot GDExtensions

    --passC: "-s SIDE_MODULE=1 -s SUPPORT_LONGJMP='wasm'"
    --passL: "-s SIDE_MODULE=1 -s SUPPORT_LONGJMP='wasm' -s WASM_BIGINT"

```

This configuration tells the Nim compiler to generate Wasm32 bytecode and passes the critical `SIDE_MODULE=1` flag to Emscripten, which produces a dynamic library that Godot can load at runtime rather than a standalone executable.

## Compiling the Extension with gdextwiz

Use the `gdextwiz` CLI tool to compile your extension for the web target. As documented in [`docs/tools/gdextwiz.md`](https://github.com/godot-nim/gdext-nim/blob/main/docs/tools/gdextwiz.md) (lines 44-58), the tool automatically discovers your `bootstrap.nim` entry point and applies the settings from `config.nims`.

Build commands:

```bash

# Debug build for testing

gdextwiz build -d:platform=web

# Optimized release build for final export

gdextwiz build -d:platform=web -d:target=release

```

The `gdextwiz` command invokes `emcc` with the flags defined in your `configure()` block, generating `libmyextension.wasm` in the `res://nim/lib/` directory.

## Exporting for Godot HTML5

The final step requires configuring the Godot editor to package your Wasm side-module with the HTML5 export. According to [`docs/building-and-exporting-guide.md`](https://github.com/godot-nim/gdext-nim/blob/main/docs/building-and-exporting-guide.md) (lines 96-99), you must enable specific variant options in the export preset:

1. Open **Project → Export** and add a **Web** preset.
2. In the **Variant** section, enable **Extensions Support**.
3. Enable **Thread Support** (required for WebAssembly side-modules to function).

When you click **Export Project**, Godot copies the generated `.wasm` file into the export folder and references it through the automatically generated `.gdextension` file (controlled by `BuildSettings.extpath` and `updateMethod`). The entry point in this file points to `res://nim/lib/libmyextension.wasm`.

## Understanding the Side-Module Architecture

gdext-nim builds a **WebAssembly side-module** rather than a whole-program Wasm executable. This architectural choice, implemented via the `-s SIDE_MODULE=1` flag, allows Godot to load your extension dynamically at runtime while keeping the engine core separate. The side-module approach enables hot-reloading capabilities and reduces initial bundle size.

The flags `-s SUPPORT_LONGJMP='wasm'` and `-s WASM_BIGINT` are mandatory for threading support in WebAssembly side-modules. gdext-nim automatically injects these when the `web` platform is detected in your `configure()` block, ensuring compatibility with Godot's multi-threaded HTML5 builds.

## Summary

- Install Emscripten and ensure `emcc` is available on your system `PATH` before building.
- Configure `config.nims` with `--cpu: wasm32`, `--cc: clang`, and Emscripten paths to target WebAssembly.
- Pass `-s SIDE_MODULE=1 -s SUPPORT_LONGJMP='wasm' -s WASM_BIGINT` to `emcc` via `--passC` and `--passL` to generate a loadable side-module.
- Use `gdextwiz build -d:platform=web` to compile your extension; the tool handles the Nim-to-C-to-Wasm pipeline automatically.
- Enable **Extensions Support** and **Thread Support** in the Godot HTML5 export preset to allow the engine to load your Wasm side-module.
- The `.gdextension` file is auto-generated based on `BuildSettings`, pointing to the compiled `libmyextension.wasm` in `res://nim/lib/`.

## Frequently Asked Questions

### What is a WebAssembly side-module and why does gdext-nim use one?

A WebAssembly side-module is a dynamically linkable Wasm binary that exports symbols for a host environment to load at runtime. gdext-nim uses this architecture—enabled by the `-s SIDE_MODULE=1` flag—to produce a GDExtension library that Godot loads on demand, keeping the engine core separate from extension code and enabling hot-reloading functionality in the HTML5 export.

### Why do I need to enable Thread Support in the Godot export preset?

WebAssembly side-modules require threading primitives to interface correctly with Godot's multi-threaded architecture. The `-s SUPPORT_LONGJMP='wasm'` and `-s WASM_BIGINT` flags generate the necessary threading metadata in the Wasm binary, but Godot's HTML5 export must explicitly enable **Thread Support** in the Variant settings to instantiate and run threaded side-modules in the browser.

### Can I customize the location of the generated `.gdextension` file?

Yes. In your `config.nims`, set the `extpath` field in `BuildSettings` to your desired file path, and adjust `updateMethod` to control how gdext-nim modifies the file. Use `updateMethod = inject` to preserve existing custom entries while updating paths, or `overwrite` to regenerate the file completely. The default behavior uses `create` to generate a new file at the specified path.

### Where does gdext-nim place the compiled WebAssembly binary?

By default, `gdextwiz` outputs the compiled Wasm file to `res://nim/lib/lib{name}.wasm`, where `{name}` matches your `BuildSettings.name` value. The auto-generated `.gdextension` file references this path automatically, ensuring Godot locates and loads the side-module when the HTML5 project starts.