Skip to content

development.md

Latest commit

 

History

History
163 lines (125 loc) · 8.34 KB

development.md

File metadata and controls

163 lines (125 loc) · 8.34 KB

Development Guide

Prerequisites

  • Node.js 22 or higher
  • bun — Package manager & runtime (install)
  • Python 3.11+ (for native module compilation)
  • prek — PR code checker (npm install -g @j178/prek)

Quick Start

# Clone the repository
git clone https://github.com/ActiveInAI/PanAI.git
cd PanAI

# Install dependencies
bun install

# Start development server (Electron desktop mode)
bun start

Scripts Reference

Development

Command Description
bun start Start Electron app in development mode (desktop)
bun run start:multi Start a second Electron instance alongside an existing one (see Multi-Instance)
bun run cli Alias for bun start
bun run webui Start in WebUI mode (browser-based, no Electron window)
bun run webui:remote Start in WebUI mode with remote access enabled
bun run webui:prod Start WebUI in production mode
bun run webui:prod:remote Start WebUI in production mode with remote access
bun run resetpass Reset user password via CLI

Build & Distribution

Command Description
bun run package Build all processes (main, preload, renderer) to out/
bun run make Alias for bun run package
bun run dist Build and package distributable for current platform
bun run dist:mac Build distributable for macOS
bun run dist:win Build distributable for Windows
bun run dist:linux Build distributable for Linux
bun run build-mac Build macOS distributable for both arm64 and x64
bun run build-mac:arm64 Build macOS distributable for Apple Silicon only
bun run build-mac:x64 Build macOS distributable for Intel only
bun run build-win Build Windows distributable
bun run build-win:arm64 Build Windows distributable for ARM64
bun run build-win:x64 Build Windows distributable for x64
bun run build-deb Build Linux (.deb) distributable
bun run build Alias for bun run build-mac

Standalone Server (non-Electron)

Command Description
bun run build:renderer:web Build renderer for standalone web deployment
bun run build:server Build standalone server bundle to dist-server/
bun run server:start Run standalone server in development mode
bun run server:start:remote Run standalone server with remote access
bun run server:start:prod Run standalone server in production mode
bun run server:start:prod:remote Run standalone server in production mode with remote access
bun run server:resetpass Reset password via standalone server CLI
bun run server:resetpass:prod Reset password via standalone server CLI (production)

Code Quality

Command Description
bun run lint Check for lint issues (oxlint, read-only)
bun run lint:fix Auto-fix lint issues
bun run format Auto-format code (oxfmt)
bun run format:check Check formatting without modifying files
bun run i18n:types Generate TypeScript types for i18n keys

Testing

Command Description
bun run test Run all unit tests (vitest)
bun run test:watch Run tests in watch mode
bun run test:coverage Run tests with coverage report
bun run test:contract Run contract tests
bun run test:integration Run integration tests
bun run test:bun Run Bun-specific database driver tests
bun run test:e2e Run end-to-end tests (Playwright)
bun run test:packaged:i18n Run i18n integration tests against packaged build
bun run test:packaged:bun Run Bun packaged integration tests

Debug

Command Description
bun run debug:perf Start app with performance monitoring enabled
bun run debug:perf:report Generate performance report from collected data
bun run debug:mcp Debug MCP server connections
bun run debug:mcp:list List configured MCP servers
bun run debug:mcp:validate Validate MCP server configurations
bun run debug:custom-agent Debug custom agent connections

Multi-Instance Development

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

bun run start:multi

This sets PANAI_MULTI_INSTANCE=1, which:

  • Skips the Electron single-instance lock
  • Uses a separate userData directory (PanAI-Dev-2) to avoid database and config conflicts
  • Isolates data/config symlink paths (~/.panai-dev-2, ~/.panai-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

PanAI 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