Skip to content

setup.md

Latest commit

 

History

History
148 lines (109 loc) · 4.02 KB

setup.md

File metadata and controls

148 lines (109 loc) · 4.02 KB
sidebar_position 1
sidebar_label Development Setup

Development Setup

Everything you need to build DotAgents from source.

Prerequisites

Requirement Version Purpose
Node.js 24.x recommended (min: 20.19.4) Runtime
pnpm 9.x Package manager (required)
Rust Latest stable Native keyboard/input binary
Xcode Latest (macOS only) Code signing

pnpm is required. Using npm or yarn will cause installation issues.

corepack enable
corepack prepare pnpm@9 --activate

Quick Start

git clone https://github.com/aj47/dotagents-mono.git
cd dotagents-mono
nvm use
pnpm install
pnpm --filter @dotagents/desktop build-rs    # Build Rust native binary
pnpm dev         # Start development server

Build Commands

Command Description
pnpm dev Start development server (desktop)
pnpm dev:mobile Start development server (mobile, Expo)
pnpm build Production build for current platform
pnpm --filter @dotagents/desktop build:mac macOS build (Apple Silicon + Intel universal)
pnpm --filter @dotagents/desktop build:win Windows build (x64)
pnpm --filter @dotagents/desktop build:linux Linux build for host architecture
pnpm --filter @dotagents/desktop build:linux:x64 Linux x64 build
pnpm --filter @dotagents/desktop build:linux:arm64 Linux ARM64 build
pnpm --filter @dotagents/desktop build-rs Build Rust native binary
pnpm test Run test suite
pnpm test:run Run tests once (CI mode)
pnpm test:coverage Run tests with coverage
pnpm typecheck TypeScript type checking
pnpm lint ESLint across all packages

For signing, release packaging, GitHub Actions artifacts, docs builds, and web deployments, see Build, Release, Deploy.

Debug Mode

pnpm dev d               # ALL debug logging
pnpm dev debug-llm       # LLM calls and responses
pnpm dev debug-tools     # MCP tool execution
pnpm dev debug-ui        # UI state changes

See Debug Reference for details.

Docker

Build Linux packages in a consistent environment:

docker compose run --rm build-linux         # Build Linux packages
docker compose run --rm --build build-linux # Rebuild after code changes
docker compose run --rm shell               # Interactive dev shell

Linux Architecture-Specific Builds

pnpm --filter @dotagents/desktop build:linux:x64
pnpm --filter @dotagents/desktop build:linux:arm64

Override packaging targets:

DOTAGENTS_LINUX_TARGETS=AppImage,deb pnpm --filter @dotagents/desktop build:linux:arm64

Mobile Development

pnpm --filter @dotagents/mobile start    # Start Metro bundler
pnpm --filter @dotagents/mobile ios      # iOS (requires Xcode)
pnpm --filter @dotagents/mobile android  # Android (requires Android Studio)
pnpm --filter @dotagents/mobile web      # Web

Testing

pnpm test                    # Watch mode
pnpm test:run                # Single run (CI)
pnpm test:coverage           # With coverage report

Tests use Vitest and are located alongside source files as *.test.ts and *.test.tsx.

Troubleshooting

"Electron uninstall" error

rm -rf node_modules && pnpm install

Multiple lock files

rm -f package-lock.json bun.lock
rm -rf node_modules && pnpm install

Windows: "not a valid Win32 application"

pnpm install --ignore-scripts
pnpm.cmd -C apps/desktop exec electron-builder install-app-deps

Node version mismatch

nvm use    # Uses the repository .nvmrc

Next Steps