How to Set Up a Development Environment for moeru-ai/airi

Clone the repository, enable corepack to install pnpm, run pnpm install and cargo fetch, then start the web app with pnpm dev or the desktop app with pnpm dev:tamagotchi.

Project AIRI is a monorepo that combines desktop (Electron), web (Vue 3), and mobile (Capacitor) frontends with a Rust-backed server, organized as pnpm workspaces. Setting up a development environment for moeru-ai/airi requires Node.js 23+, the Rust toolchain for native components, and pnpm via corepack. This guide provides the exact commands and file paths needed to build and run each component of the codebase according to the .github/CONTRIBUTING.md specifications.

Prerequisites

Core Toolchain

You need the following tools installed before cloning the repository:

• Git – any recent version
• Node.js 23+ – the runtime required by the workspace configuration
• corepack – bundled with Node.js, enables pnpm without global installation
• pnpm – installed via corepack prepare pnpm@latest --activate

These baseline requirements are documented in .github/CONTRIBUTING.md lines 5-11.

Rust and System Dependencies

For the desktop Electron app or server components, additional tooling is required:

• Rust toolchain (stable) – install with rustup toolchain install stable
• Linux desktop libraries (Ubuntu/Debian) – required only for Electron development:

sudo apt install libssl-dev libglib2.0-dev libgtk-3-dev libjavascriptcoregtk-4.1-dev libwebkit2gtk-4.1-dev

These system dependencies are specified in the Contributing Guide at lines 83-91.

Clone and Configure the Repository

Fork the repository on GitHub, then clone your fork and configure the upstream remote:

git clone https://github.com/<your-github-username>/airi.git
cd airi
git remote add upstream https://github.com/moeru-ai/airi.git
git fetch --all

This workflow ensures you can sync with the main branch using git pull upstream main --rebase as recommended in the "If you have already contributed" section of .github/CONTRIBUTING.md.

Install Dependencies

Enable corepack and install JavaScript dependencies across all workspaces:

corepack enable
corepack prepare pnpm@latest --activate
pnpm install

For Rust components used by the desktop and server:

cargo fetch

The repository uses pnpm workspaces defined in pnpm-workspace.yaml to share node_modules across packages, ensuring consistent versions for the Vite-based build system.

Start the Development Server

Choose the target application from the available workspaces:

• Web (Stage Web): pnpm dev – starts the Vite dev server at http://localhost:5173 as configured in apps/stage-web/vite.config.ts
• Desktop (Stage Tamagotchi): pnpm dev:tamagotchi – launches the Electron app with hot-reloading using apps/stage-tamagotchi/electron.vite.config.ts
• Documentation: pnpm dev:docs – serves the documentation UI
• Mobile: pnpm dev:pocket:ios <DEVICE> – builds and runs the iOS simulator (Capacitor)

These commands are documented in .github/CONTRIBUTING.md lines 61-89 and leverage the shared packages defined in pnpm-workspace.yaml.

Verify Your Environment

Run the linting and type-checking scripts to ensure everything compiles correctly:

pnpm lint && pnpm typecheck

If these commands succeed, your development environment is correctly configured. Errors typically indicate missing Node.js 23+ or an incomplete Rust toolchain for the desktop components.

Development Workflow

Follow this workflow when contributing to moeru-ai/airi:

1. Create a feature branch: git checkout -b feature/your-feature-name
2. Make changes in apps/ or packages/ directories
3. Run targeted tests: pnpm -F @proj-airi/stage-ui exec vitest run
4. Lint and type-check: pnpm lint && pnpm typecheck
5. Commit and push: Use conventional commits and push to your fork
6. Open a Pull Request against the upstream repository

This process aligns with the contribution guidelines in .github/CONTRIBUTING.md lines 48-55.

Key Project Files

Understanding these configuration files helps navigate the codebase:

• .github/CONTRIBUTING.md – Complete onboarding guide with all prerequisites and development commands
• pnpm-workspace.yaml – Declares the monorepo workspace structure and package locations
• uno.config.ts – Global UnoCSS configuration used for styling across all applications
• apps/stage-web/vite.config.ts – Vite configuration for the web frontend build
• apps/stage-tamagotchi/electron.vite.config.ts – Vite configuration for the Electron desktop build
• packages/stage-ui/src/ – Shared Vue 3 components, composables, and stores used by multiple frontends
• packages/server-runtime/ – Server-side runtime implementation (WebSocket, gRPC)
• AGENTS.md – Internal developer guide describing tech stack conventions and architecture decisions

Summary

• Install Node.js 23+ and enable corepack to manage the correct pnpm version
• Run pnpm install for JavaScript dependencies and cargo fetch for Rust crates when working on desktop or server components
• Use pnpm dev for web development, pnpm dev:tamagotchi for desktop, or pnpm dev:docs for documentation
• Verify changes with pnpm lint && pnpm typecheck before committing
• Reference .github/CONTRIBUTING.md and AGENTS.md for detailed conventions and architecture guidance

Frequently Asked Questions

Do I need Rust for web-only development in moeru-ai/airi?

No. According to .github/CONTRIBUTING.md, the Rust toolchain is only required for the desktop Electron app (apps/stage-tamagotchi) and server crates (packages/server-runtime). Pure web development using pnpm dev relies only on Node.js and pnpm.

What Node.js version is required?

The repository requires Node.js 23 or higher as specified in the Contributing Guide. Older versions may cause compatibility issues with the workspace configuration or Vite build plugins.

How do I switch between web and desktop development?

Run pnpm dev to start the Stage Web application at http://localhost:5173, or execute pnpm dev:tamagotchi to launch the Electron desktop environment. Both commands share the same underlying packages in packages/stage-ui/ but target different application entry points.

Where are shared UI components located?

Reusable Vue 3 components reside in packages/stage-ui/src/components/ as documented in AGENTS.md lines 28-34. This package is consumed by both the web and desktop applications to maintain consistent UI behavior across platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}