---
title: Extensions
url: "https://native-sdk.dev/docs/extensions"
docs_index: /llms.txt
lastUpdated: 2026-10-16
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The `ModuleRegistry` provides a hook-based extension system for adding modular capabilities to the runtime.

## Module structure

Each module has an info block, a context pointer, and optional lifecycle hooks:

```zig
const MyModule = struct {
    data: u32 = 0,

    fn start(context: *anyopaque, runtime: native_sdk.extensions.RuntimeContext) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        self.data = 42;
    }

    fn command(context: *anyopaque, runtime: native_sdk.extensions.RuntimeContext, cmd: native_sdk.extensions.Command) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        if (std.mem.eql(u8, cmd.name, "reset")) self.data = 0;
    }
};
```

## Registering modules

```zig
var my_module = MyModule{};
const caps = [_]native_sdk.extensions.Capability{.{ .kind = .native_module }};
const modules = [_]native_sdk.extensions.Module{.{
    .info = .{ .id = 1, .name = "my-module", .capabilities = &caps },
    .context = &my_module,
    .hooks = .{ .start_fn = MyModule.start, .command_fn = MyModule.command },
}};
const registry = native_sdk.extensions.ModuleRegistry{ .modules = &modules };

var runtime = native_sdk.Runtime.init(.{
    .platform = my_platform,
    .extensions = registry,
});
```

## Module fields

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `info.id`
      </td>

      <td>
        `u64`
      </td>

      <td>
        Unique numeric identifier (duplicates rejected at validation)
      </td>
    </tr>

    <tr>
      <td>
        `info.name`
      </td>

      <td>
        `[]const u8`
      </td>

      <td>
        Human-readable module name
      </td>
    </tr>

    <tr>
      <td>
        `info.capabilities`
      </td>

      <td>
        `[]const Capability`
      </td>

      <td>
        Capabilities this module provides
      </td>
    </tr>

    <tr>
      <td>
        `context`
      </td>

      <td>
        `*anyopaque`
      </td>

      <td>
        Opaque pointer to module state
      </td>
    </tr>

    <tr>
      <td>
        `hooks.start_fn`
      </td>

      <td>
        optional
      </td>

      <td>
        Called when the runtime starts
      </td>
    </tr>

    <tr>
      <td>
        `hooks.stop_fn`
      </td>

      <td>
        optional
      </td>

      <td>
        Called when the runtime stops (reverse registration order)
      </td>
    </tr>

    <tr>
      <td>
        `hooks.command_fn`
      </td>

      <td>
        optional
      </td>

      <td>
        Called when a command is dispatched to modules
      </td>
    </tr>
  </tbody>
</table>

## Registry methods

<table>
  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `validate()`
      </td>

      <td>
        Check for duplicate module IDs
      </td>
    </tr>

    <tr>
      <td>
        `startAll(runtime)`
      </td>

      <td>
        Call

        `start_fn`

        on all modules
      </td>
    </tr>

    <tr>
      <td>
        `stopAll(runtime)`
      </td>

      <td>
        Call

        `stop_fn`

        on all modules (reverse order)
      </td>
    </tr>

    <tr>
      <td>
        `dispatchCommand(runtime, command)`
      </td>

      <td>
        Call

        `command_fn`

        on all modules
      </td>
    </tr>

    <tr>
      <td>
        `hasCapability(kind)`
      </td>

      <td>
        Check if any module provides a capability
      </td>
    </tr>
  </tbody>
</table>

## Capability kinds

<table>
  <thead>
    <tr>
      <th>
        Kind
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `native_module`
      </td>

      <td>
        A native Zig module
      </td>
    </tr>

    <tr>
      <td>
        `webview`
      </td>

      <td>
        WebView rendering
      </td>
    </tr>

    <tr>
      <td>
        `js_bridge`
      </td>

      <td>
        JavaScript bridge
      </td>
    </tr>

    <tr>
      <td>
        `filesystem`
      </td>

      <td>
        File system access
      </td>
    </tr>

    <tr>
      <td>
        `network`
      </td>

      <td>
        Network access
      </td>
    </tr>

    <tr>
      <td>
        `clipboard`
      </td>

      <td>
        Clipboard access
      </td>
    </tr>

    <tr>
      <td>
        `custom`
      </td>

      <td>
        Custom capability (with a

        `name`

        field)
      </td>
    </tr>
  </tbody>
</table>

These correspond to capability kinds used by the [app manifest](/docs/app-zon). The runtime can query whether any module provides a given capability using `registry.hasCapability(.filesystem)`.

## Native JS engine (experimental)

The `js` module provides an abstraction layer for calling into a native JavaScript engine from Zig. This is separate from the WebView bridge and is intended for future native module integrations.

<table>
  <thead>
    <tr>
      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `Value`
      </td>

      <td>
        Tagged union:

        `null`

        ,

        `boolean`

        ,

        `number`

        ,

        `string`
      </td>
    </tr>

    <tr>
      <td>
        `Call`
      </td>

      <td>
        A function call:

        `module`

        ,

        `function`

        ,

        `args`
      </td>
    </tr>

    <tr>
      <td>
        `Bridge`
      </td>

      <td>
        Validates and dispatches calls via

        `RuntimeHooks`
      </td>
    </tr>

    <tr>
      <td>
        `NullEngine`
      </td>

      <td>
        Stub that returns

        `EngineUnavailable`
      </td>
    </tr>
  </tbody>
</table>

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)