Development Guide

Prerequisites

• Node.js 22 or higher
• bun — Package manager & runtime (install)
• Rust stable + Cargo — Required to build the local AionCore backend (install)
• Python 3.11+ (for native module compilation)
• prek — PR code checker (npm install -g @j178/prek)

On Windows, install the Rust MSVC toolchain. If Rust compilation fails because native build tools are missing, install Microsoft C++ Build Tools from the Visual Studio installer, then reopen your terminal.

Repository Layout

AionUi development uses two repositories:

• AionCore (https://github.com/iOfficeAI/AionCore.git) builds the local backend binary: aioncore on macOS/Linux and aioncore.exe on Windows.
• AionUi (https://github.com/iOfficeAI/AionUi.git) starts the Electron desktop app and launches the backend binary automatically.

Keep the repositories side by side when possible:

workspace/
|-- AionCore/
`-- AionUi/

The desktop development server resolves the backend from the PATH inherited by bun run start. Install AionCore first, verify the binary is discoverable in the same terminal, then start AionUi.

Quick Start

1. Clone Both Repositories

git clone https://github.com/iOfficeAI/AionCore.git
git clone https://github.com/iOfficeAI/AionUi.git

Use the main branch for both repositories unless a maintainer asks you to test another branch.

2. Build and Install AionCore

Run these commands from the AionCore repository.

macOS / Linux

cd AionCore
cargo clean
cargo install --path crates/aionui-app --locked

# Make Cargo-installed binaries visible to this shell if needed.
export PATH="$HOME/.cargo/bin:$PATH"

# Verify that AionUi will be able to find the backend.
which aioncore
aioncore --help

If which aioncore prints nothing, add export PATH="$HOME/.cargo/bin:$PATH" to your shell profile (~/.zshrc, ~/.bashrc, or your shell's equivalent), open a new terminal, and verify again.

Windows PowerShell

cd AionCore
cargo clean
cargo install --path crates/aionui-app --locked

# Make Cargo-installed binaries visible to this PowerShell session if needed.
$env:Path = "$env:USERPROFILE\.cargo\bin;$env:Path"

# Verify that AionUi will be able to find the backend.
where.exe aioncore
aioncore --help

If where.exe aioncore prints nothing, make sure %USERPROFILE%\.cargo\bin is in your user Path, open a new PowerShell window, and verify again.

3. Start AionUi

Run these commands from the AionUi repository in a terminal where aioncore is discoverable.

cd AionUi

# Install dependencies
bun install

# Start the Electron desktop app in development mode
bun run start

During startup, AionUi launches aioncore automatically and passes the backend port to the renderer. You do not need to start AionCore in a separate terminal.

Updating the Local Backend

When you pull or change AionCore, reinstall the backend binary and restart AionUi:

cd ../AionCore
cargo install --path crates/aionui-app --locked --force

cd ../AionUi
bun run start

Use --force when rebuilding local changes with the same AionCore package version; otherwise Cargo may keep the already installed binary.

Backend Startup Troubleshooting

Cannot find "aioncore" binary

AionUi cannot find the backend from the PATH inherited by bun run start.

Check from the same terminal where you start AionUi:

# macOS / Linux
which aioncore

# Windows PowerShell
where.exe aioncore

If the command fails, add Cargo's binary directory to PATH and start AionUi from a new terminal.

aioncore Works in a Terminal but AionUi Still Cannot Find It

Make sure you start bun run start from the same terminal environment that can run aioncore --help. IDE terminals and GUI-launched shells can inherit a different PATH; restart the IDE or launch it from a terminal after updating PATH.

Backend Changes Do Not Show Up

Quit AionUi, reinstall AionCore with cargo install --path crates/aionui-app --locked --force, then start AionUi again. The Electron app owns the backend subprocess during development, so a running AionUi instance will not pick up a newly installed binary until it restarts.

Windows Rust Build Errors

Use the Rust MSVC toolchain and install Microsoft C++ Build Tools. After installing or changing toolchains, open a new PowerShell window and rerun the AionCore install command.

Scripts Reference

Development

Build & Distribution

Standalone Server (non-Electron)

Code Quality

Testing

Debug

Multi-Instance Development

When you have two clones of the repository (e.g. AionUi and AionUi-refactor) and need to run both simultaneously, the second instance can be started with:

bun run start:multi

This sets AIONUI_MULTI_INSTANCE=1, which:

• Skips the Electron single-instance lock
• Uses a separate userData directory (AionUi-Dev-2) to avoid database and config conflicts
• Isolates data/config symlink paths (~/.aionui-dev-2, ~/.aionui-config-dev-2)
• Vite renderer, CDP, and WebUI proxy ports auto-increment to avoid collisions

Note: The multi-instance WebUI defaults to port 25810 (instead of 25809). When accessing WebUI in a browser, use an incognito/private window for the second instance — both instances share the localhost cookie jar, and their JWT secrets differ, causing authentication failures if the same browser session is reused.

Code Checks (prek)

The project uses prek (a Rust implementation of pre-commit) for code checks, configured in .pre-commit-config.yaml:

# Install prek
npm install -g @j178/prek

# Install git hooks (optional, auto-check before commit)
prek install

# Run checks on staged files
prek run

# Run checks on changes vs main (same as CI)
prek run --from-ref origin/main --to-ref HEAD

Build System

AionUi uses electron-vite for fast bundling:

• Main process: bundled with Vite (ESM)
• Renderer process: bundled with Vite (React + TypeScript)
• Preload scripts: bundled with Vite

The build output goes to out/ directory:

• out/main/ - Main process code
• out/renderer/ - Renderer process code
• out/preload/ - Preload scripts

Tech Stack

• Electron - Cross-platform desktop framework
• React 19 - UI framework
• TypeScript - Type safety
• Vite - Fast bundler (via electron-vite)
• UnoCSS - Atomic CSS engine
• better-sqlite3 - Local database
• vitest - Testing framework