Documentation

Module development

Extend IWE Code with external modules. Package a program, describe its panel in JSON, and install it from a file.

An external module is a separate program that IWE Code runs and talks to over a simple JSON protocol. Write it in any language, ship binaries for your platforms, and install the package without recompiling the application.

How it works

  • Your module runs as its own process. IWE Code starts it when you enable the module and stops it when you disable or remove the module.
  • The host and the module exchange one JSON document per line through the standard input and output of the process.
  • The module describes its panel with a declarative widget tree. IWE Code renders the panel with its own native components.
  • The module localizes its own panel text. The host reports the interface language at startup.

The manifest

Every package contains a manifest.json file that describes the module.

id
Unique identifier in lower-case kebab style, for example hello-module.
name, description
Localized texts. English is required; Russian and Spanish are optional.
version
Semantic version of the module. Updates must increase it.
api
Protocol version. The current version is 1.
minAppVersion
Minimum application version the module supports.
entry
Executable file name per platform target, for example macos-aarch64.
permissions
Declared access: filesystem-read, filesystem-write, network, process.
placement
Workspace zone for the panel: header, top, left, right, or bottom.
{
  "id": "hello-module",
  "name": { "en": "Hello module", "ru": "Модуль приветствия" },
  "description": { "en": "Shows a friendly panel." },
  "version": "1.0.0",
  "api": 1,
  "minAppVersion": "1.0.8",
  "entry": { "macos-aarch64": "hello-module", "linux-x86_64": "hello-module" },
  "permissions": [],
  "placement": "bottom"
}

Package layout

A package is a gzipped tar archive with the .iwe-module extension.

hello-module/
├── manifest.json
├── manifest.sig
└── binaries/
    ├── macos-aarch64/hello-module
    └── linux-x86_64/hello-module

Protocol messages

Every message is a single JSON line. Unknown messages are ignored, so modules can stay simple.

{"type":"initialize","api":1,"appVersion":"1.0.8","language":"en","installPath":"/…/modules/hello-module/1.0.0"}
{"type":"panel","content":{"type":"column","children":[{"type":"text","content":"Hello!"}]}}
{"type":"event","id":"click","action":{"type":"click"}}
{"type":"notify","level":"info","message":"Done"}
{"type":"shutdown"}

From IWE Code to the module

initialize
Sent once at startup. Reports the protocol version, application version, interface language, and the installation path.
event
Reports a widget interaction: a click, a toggle, or a text change.
shutdown
Asks the module to exit.

From the module to IWE Code

panel
Replaces the panel content with a new widget tree.
notify
Shows a short message with an info, warning, or error level.

Panel widgets

A panel is a tree of simple nodes. Each node has a type and its own fields.

column, row
Stack child nodes vertically or horizontally with an optional spacing.
text
Show text with a body, heading, caption, muted, or danger style.
button
A labeled button that reports a click. Styles: primary, secondary, danger.
text-input
A single-line input that reports value changes.
checkbox, toggle
Boolean controls that report their new state.
progress
A progress bar between 0 and 1.
separator, scroll, spacer
Layout helpers for dividing, scrolling, and filling space.

Permissions

The manifest declares the access a module needs. IWE Code shows this list before installation and asks for confirmation. Modules run with your user rights; IWE Code does not sandbox them. Install modules you trust.

filesystem-read
Read files on your computer.
filesystem-write
Change files on your computer.
network
Reach the network.
process
Start other programs.

Build a package

Build the reference module, assemble the package folder, and compress it. The example is a complete Rust module you can copy.

cargo build --release --example hello-module
mkdir -p hello-module/binaries/macos-aarch64
cp target/release/examples/hello-module hello-module/binaries/macos-aarch64/
cp manifest.json hello-module/
tar -czf hello-module.iwe-module -C hello-module manifest.json binaries

Sign the package

IWE Code checks signatures and file digests. Installation rejects unsigned or modified packages.

The signing script requires the maintainer’s Ed25519 key. See the package reference for details.

python3 .github/scripts/sign-module.py hello-module.iwe-module

Install

Open Settings → Modules in IWE Code, choose Install from file…, review the requested access, and confirm. Updates install the same way with a higher version number.

Reference module

The repository contains a working example under examples/hello-module.

Full reference