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

> Set up your moeru-ai/airi development environment easily. Clone the repo, install dependencies with pnpm, fetch Rust crates, and run the web or desktop app.

- Repository: [Moeru AI/airi](https://github.com/moeru-ai/airi)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/moeru-ai/airi/blob/main/.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`](https://github.com/moeru-ai/airi/blob/main/.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:

```bash
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:

```bash
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`](https://github.com/moeru-ai/airi/blob/main/.github/CONTRIBUTING.md).

## Install Dependencies

Enable corepack and install JavaScript dependencies across all workspaces:

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

```

For Rust components used by the desktop and server:

```bash
cargo fetch

```

The repository uses **pnpm workspaces** defined in [`pnpm-workspace.yaml`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/.github/CONTRIBUTING.md) lines 61-89 and leverage the shared packages defined in [`pnpm-workspace.yaml`](https://github.com/moeru-ai/airi/blob/main/pnpm-workspace.yaml).

## Verify Your Environment

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

```bash
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`](https://github.com/moeru-ai/airi/blob/main/.github/CONTRIBUTING.md) lines 48-55.

## Key Project Files

Understanding these configuration files helps navigate the codebase:

- **[`.github/CONTRIBUTING.md`](https://github.com/moeru-ai/airi/blob/main/.github/CONTRIBUTING.md)** – Complete onboarding guide with all prerequisites and development commands
- **[`pnpm-workspace.yaml`](https://github.com/moeru-ai/airi/blob/main/pnpm-workspace.yaml)** – Declares the monorepo workspace structure and package locations
- **[`uno.config.ts`](https://github.com/moeru-ai/airi/blob/main/uno.config.ts)** – Global UnoCSS configuration used for styling across all applications
- **[`apps/stage-web/vite.config.ts`](https://github.com/moeru-ai/airi/blob/main/apps/stage-web/vite.config.ts)** – Vite configuration for the web frontend build
- **[`apps/stage-tamagotchi/electron.vite.config.ts`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/.github/CONTRIBUTING.md) and [`AGENTS.md`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/.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`](https://github.com/moeru-ai/airi/blob/main/AGENTS.md) lines 28-34. This package is consumed by both the web and desktop applications to maintain consistent UI behavior across platforms.