Contributing to Project AIRI

Thank you for your interest in contributing to Project AIRI! This guide will help you get started with development, understand our workflows, and make your first contribution.

We welcome all types of contributions: code, documentation, translations, bug reports, feature requests, and community support!

Prerequisites

Before you begin, make sure you have the following installed:

Git

Version control systemDownload Git

Node.js 23+

JavaScript runtimeDownload Node.js

pnpm

Fast, disk space efficient package manager

corepack enable
corepack prepare pnpm@latest --activate

corepack

Package manager manager (comes with Node.js)Already included with Node.js 16+

Platform-Specific Setup

Windows
macOS
Linux

Install Visual Studio

Download Visual Studio and install:

Windows SDK
C++ build tools

Follow: https://rust-lang.github.io/rustup/installation/windows-msvc.html#walkthrough-installing-visual-studio-2022

Install Scoop

Open PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

Install Dependencies

scoop install git nodejs rustup

# For Rust dependencies (optional, only for crates/)
scoop install main/rust-msvc
rustup toolchain install stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-msvc

Install pnpm

corepack enable
corepack prepare pnpm@latest --activate

Open Terminal

Use Terminal, iTerm2, Ghostty, Kitty, or your preferred terminal.

Install Homebrew

If you don’t have Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Dependencies

brew install git node

Install pnpm

corepack enable
corepack prepare pnpm@latest --activate

Install Node.js

Follow NodeSource distributions

Install Git

Follow Git installation guide

Install pnpm

corepack enable
corepack prepare pnpm@latest --activate

Desktop Development Dependencies (Optional)

For developing the desktop version:

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

Optional: Install @antfu/ni

For a simpler development experience:

npm i -g @antfu/ni

With ni installed, you can:

Use ni instead of pnpm install, npm install, yarn install
Use nr instead of pnpm run, npm run, yarn run

Getting Started

Fork and Clone

Fork the Repository

Click the Fork button on the moeru-ai/airi repository page.

Clone Your Fork

git clone https://github.com/<your-github-username>/airi.git
cd airi

Add Upstream Remote

git remote add upstream https://github.com/moeru-ai/airi.git

Install Dependencies

corepack enable
pnpm install

# For Rust dependencies (optional, only if working on crates/)
cargo fetch

Create a Working Branch

git checkout -b <your-username>/<feature|fix>/<short-description>

# Examples:
git checkout -b alice/feat/add-weather-widget
git checkout -b bob/fix/memory-leak

Branch naming convention: <username>/<type>/<description>Types: feat, fix, docs, refactor, test, chore

Development Workflow

Choose Your Application

Stage Web
Stage Tamagotchi
Stage Pocket
Documentation

Browser version for airi.moeru.ai

pnpm dev
# or with ni:
nr dev

Opens at: http://localhost:5173

Desktop version (Electron)

pnpm dev:tamagotchi
# or with ni:
nr dev:tamagotchi

Launches Electron app

Mobile version (Capacitor)

# Start dev server
pnpm dev:pocket

# Note your IP address from output
# Then in another terminal:
CAPACITOR_DEV_SERVER_URL=https://<your-ip>:5273 pnpm open:ios

Documentation site

pnpm dev:docs
# or with ni:
nr dev:docs

Opens at: http://localhost:3000

Monorepo Commands

Workspace Filters

Use pnpm filters to scope commands to specific packages:

# Run command in specific workspace
pnpm -F <package-name> <command>

# Examples:
pnpm -F @proj-airi/stage-web dev
pnpm -F @proj-airi/stage-tamagotchi build
pnpm -F @proj-airi/stage-ui typecheck

Common Commands

Development

# Run all apps in parallel
pnpm dev:apps

# Run all packages in dev mode
pnpm dev:packages

# Specific apps
pnpm dev              # Stage Web
pnpm dev:tamagotchi   # Desktop
pnpm dev:pocket       # Mobile
pnpm dev:docs         # Documentation
pnpm dev:ui           # UI Storybook

Build

# Build everything
pnpm build

# Build packages only
pnpm build:packages

# Build apps only
pnpm build:apps

# Build specific workspace
pnpm -F @proj-airi/stage-web build

# Build Rust crates (optional)
pnpm build:crates

Type Checking

# Typecheck all workspaces
pnpm typecheck

# Typecheck specific workspace
pnpm -F @proj-airi/stage-tamagotchi typecheck

# Split checks for Electron
pnpm -F @proj-airi/stage-tamagotchi typecheck:node
pnpm -F @proj-airi/stage-tamagotchi typecheck:web

Linting

# Lint all files
pnpm lint

# Lint and fix
pnpm lint:fix

# Lint Rust code
pnpm lint:rust

# Lint Swift code (mobile)
pnpm lint:swift

Testing

# Run all tests
pnpm test:run

# Run tests with coverage
pnpm test

# Run specific test file
pnpm exec vitest run <path-to-test-file>

# Run tests in specific workspace
pnpm -F @proj-airi/stage-tamagotchi exec vitest run

Development Services

Discord Bot
Telegram Bot
Minecraft Agent

cd services/discord-bot

# Configure environment
cp .env .env.local
# Edit .env.local with your credentials

# Run the bot
pnpm -F @proj-airi/discord-bot start

cd services/telegram-bot

# Start PostgreSQL
docker compose up -d

# Configure environment
cp .env .env.local
# Edit .env.local with your credentials

# Migrate database
pnpm -F @proj-airi/telegram-bot db:generate
pnpm -F @proj-airi/telegram-bot db:push

# Run the bot
pnpm -F @proj-airi/telegram-bot start

cd services/minecraft

# Configure environment
cp .env .env.local
# Edit .env.local with Minecraft server details

# Run the agent
pnpm -F @proj-airi/minecraft-bot start

Code Style and Conventions

TypeScript

File Naming
Functions
Imports

Use kebab-case for all files:

✅ my-component.vue
✅ user-store.ts
✅ fetch-data.ts

❌ MyComponent.vue
❌ UserStore.ts
❌ fetchData.ts

Prefer functional patterns over classes:

// ✅ Good: Functional
export function calculateDistance(a: Point, b: Point): number {
  return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2)
}

// ❌ Bad: Class (unless extending browser APIs)
export class DistanceCalculator {
  calculate(a: Point, b: Point): number {
    return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2)
  }
}

Organize imports logically:

// External dependencies
import { ref, computed } from 'vue'
import { useRoute } from 'vue-router'

// Internal dependencies
import { useCharacter } from '@proj-airi/stage-ui'
import { Client } from '@proj-airi/server-sdk'

// Local imports
import { formatDate } from './utils'
import type { User } from './types'

Vue Components

<script setup lang="ts">
import { ref, computed } from 'vue'

// Props
interface Props {
  title: string
  count?: number
}

const props = withDefaults(defineProps<Props>(), {
  count: 0,
})

// Emits
interface Emits {
  update: [value: number]
}

const emit = defineEmits<Emits>()

// State
const localCount = ref(props.count)

// Computed
const displayText = computed(() => `${props.title}: ${localCount.value}`)

// Methods
function increment() {
  localCount.value++
  emit('update', localCount.value)
}
</script>

<template>
  <div :class="[
    'p-4',
    'bg-white dark:bg-black',
    'rounded-lg',
  ]">
    <h2 class="text-xl font-bold mb-2">
      {{ displayText }}
    </h2>
    <button 
      :class="[
        'px-4 py-2',
        'bg-blue-500 hover:bg-blue-600',
        'text-white',
        'rounded',
      ]"
      @click="increment"
    >
      Increment
    </button>
  </div>
</template>

<style scoped>
/* Prefer UnoCSS over scoped styles */
</style>

Comments

Documentation
Markers
Workarounds

Add clear comments for complex logic:

/**
 * Calculates the optimal path using A* algorithm
 * @param start - Starting position
 * @param end - Target position
 * @param obstacles - List of impassable positions
 * @returns Array of positions representing the path
 */
export function findPath(
  start: Position,
  end: Position,
  obstacles: Position[]
): Position[] {
  // Implementation
}

Use standard markers:

// TODO: Implement caching for better performance

// REVIEW: This might cause memory leaks

// NOTICE: Workaround for Electron IPC limitation
// See: https://github.com/electron/electron/issues/12345

Document workarounds with context:

// NOTICE: Using setTimeout instead of requestIdleCallback
// because Safari doesn't support requestIdleCallback as of 2026
// Root cause: WebKit bug #123456
// Reference: https://bugs.webkit.org/show_bug.cgi?id=123456
setTimeout(doWork, 0)

Commit Guidelines

Before Committing

Always run lint and typecheck before committing!

# Lint and fix issues
pnpm lint:fix

# Type check
pnpm typecheck

# Run tests
pnpm test:run

Image Optimization

If committing images, convert to AVIF:

pnpm to-avif <PATH_TO_IMAGE_OR_DIRECTORY>

# Example:
pnpm to-avif docs/images/screenshot.png

Commit Messages

Use Conventional Commits:

# Format
<type>(<scope>): <description>

# Examples
feat(stage-ui): add weather widget component
fix(server-runtime): resolve memory leak in peer registry
docs: update plugin development guide
refactor(stage-web): improve chat message rendering
test(stage-tamagotchi): add tests for settings store
chore: update dependencies

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks
perf: Performance improvements

Optional: Use gitmoji (emoji prefix)

✨ feat(stage-ui): add weather widget component
🐛 fix(server-runtime): resolve memory leak
📝 docs: update plugin development guide

Making the Commit

# Stage changes
git add .

# Commit with message
git commit -m "feat(stage-ui): add weather widget component"

# Push to your fork
git push origin <your-branch-name> -u

Creating a Pull Request

Push Your Branch

git push origin <your-branch-name> -u

Open Pull Request

Navigate to moeru-ai/airi
Click Pull requests tab
Click New pull request
Click Compare across forks
Select your fork and branch

Fill PR Template

Provide:

Clear title and description
What changes were made
Why the changes were needed
How to test the changes
Screenshots/videos if UI changes
Related issues (if any)

Wait for Review

Maintainers will review your PR and may request changes.

PR Checklist

Code follows project style guidelines
All tests pass (pnpm test:run)
Types are correct (pnpm typecheck)
Code is linted (pnpm lint)
Commits follow conventional commit format
PR description is clear and complete
Related documentation updated (if needed)
Breaking changes documented (if any)

Keeping Your Fork Updated

# Fetch latest changes
git fetch --all

# Switch to main branch
git checkout main

# Pull latest from upstream
git pull upstream main --rebase

# Update your fork
git push origin main

# Rebase your feature branch (optional)
git checkout <your-branch-name>
git rebase main

Development Best Practices

Module Boundaries

Keep clear module boundaries. Shared logic goes in packages/, app-specific code stays in apps/.

DI Pattern

Use dependency injection (injeca) for better testability and modularity.

Type Safety

Use TypeScript strictly. Avoid any type unless absolutely necessary.

Progressive Refactoring

Improve code you touch. Small refactors are better than big rewrites.

When to Refactor

Do Refactor
Don't Refactor

When touching legacy code
To improve readability
To remove duplication
To fix code smells
Alongside feature work

Testing Your Changes

Manual Testing

Build the project: pnpm build
Run the app: pnpm dev or pnpm dev:tamagotchi
Test your changes: Follow the test scenarios from your PR description
Test edge cases: Try to break your implementation
Test on different browsers/platforms: If applicable

Automated Testing

# Run unit tests
pnpm test:run

# Run tests with coverage
pnpm test

# Run specific test
pnpm exec vitest run path/to/test.test.ts

# Watch mode (during development)
pnpm exec vitest

Community Guidelines

Communication

Discord

Join our Discord server for real-time chat

GitHub Discussions

Ask questions and share ideas

GitHub Issues

Report bugs and request features

Twitter/X

Follow for project updates

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Assume good intentions
Give constructive feedback
Focus on the code, not the person
Follow project guidelines

Getting Help

I'm stuck on setup

Check the prerequisites section
Make sure you’re using Node.js 23+
Try rm -rf node_modules && pnpm install
Ask in Discord #help channel

My PR was rejected

Don’t worry! Rejection doesn’t mean your contribution isn’t valuable:

Read the review feedback carefully
Ask clarifying questions if needed
Make the requested changes
Push updates to your branch
The PR will be re-reviewed automatically

How do I find something to work on?

Check Good First Issues
Look for issues labeled help wanted
Ask in Discord what needs help
Improve documentation (always needed!)
Fix bugs you encounter

Can I contribute without coding?

Absolutely! We need:

Documentation writers: Improve guides and tutorials
Translators: Help with i18n on Crowdin
Designers: UI/UX improvements, Live2D models, VRM models
Testers: Report bugs, test PRs
Community helpers: Answer questions, help newcomers
Artists: Create promotional materials, screenshots

Non-Code Contributions

Translations

We use Crowdin for translations:

Create a Crowdin account
Join the Project AIRI project
Select your language
Translate strings
Translations will be synced automatically

Documentation

Improve documentation in docs/:

# Start docs dev server
pnpm dev:docs

# Edit MDX files in docs/content/
# Create new pages as needed
# Follow Mintlify syntax

Bug Reports

Good bug reports include:

Clear title and description
Steps to reproduce
Expected vs actual behavior
Environment (OS, browser, version)
Screenshots/videos
Error messages/logs

Feature Requests

Good feature requests include:

Clear use case
Why it’s valuable
How it should work
Alternatives considered
Willingness to implement (optional)

Resources

Architecture Guide

Understand the codebase structure

Plugin Development

Learn to build plugins

AGENTS.md

Agent development guide

Discord Community

Join the community

Congratulations!

You’re now ready to contribute to Project AIRI! Remember:

Start small
Ask questions
Learn from feedback
Help others
Have fun!

Thank you for contributing to Project AIRI! Every contribution, no matter how small, helps make AIRI better for everyone.

​Contributing to Project AIRI

​Prerequisites

Git

Node.js 23+

pnpm

corepack

​Platform-Specific Setup

​Optional: Install @antfu/ni

​Getting Started

​Fork and Clone

​Install Dependencies

​Create a Working Branch

​Development Workflow

​Choose Your Application

​Monorepo Commands

​Workspace Filters

​Common Commands

​Development Services

​Code Style and Conventions

​TypeScript

​Vue Components

​Comments

​Commit Guidelines

​Before Committing

​Image Optimization

​Commit Messages

​Making the Commit

​Creating a Pull Request

​PR Checklist

​Keeping Your Fork Updated

​Development Best Practices

Module Boundaries

DI Pattern

Type Safety

Progressive Refactoring

​When to Refactor

​Testing Your Changes

​Manual Testing

​Automated Testing

​Community Guidelines

​Communication

Discord

GitHub Discussions

GitHub Issues

Twitter/X

​Code of Conduct

​Getting Help

​Non-Code Contributions

​Translations

​Documentation

​Bug Reports

​Feature Requests

​Resources

Architecture Guide

Plugin Development

AGENTS.md

Discord Community

​Congratulations!

Contributing to Project AIRI

Prerequisites

Platform-Specific Setup

Optional: Install @antfu/ni

Getting Started

Fork and Clone

Install Dependencies

Create a Working Branch

Development Workflow

Choose Your Application

Monorepo Commands

Workspace Filters

Common Commands

Development Services

Code Style and Conventions

TypeScript

Vue Components

Comments

Commit Guidelines

Before Committing

Image Optimization

Commit Messages

Making the Commit

Creating a Pull Request

PR Checklist

Keeping Your Fork Updated

Development Best Practices

When to Refactor

Testing Your Changes

Manual Testing

Automated Testing

Community Guidelines

Communication

Code of Conduct

Getting Help

Non-Code Contributions

Translations

Documentation

Bug Reports

Feature Requests

Resources

Congratulations!