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-moduleProtocol 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.