# Orca Build Dependencies: Complete Guide to Required Packages

> Learn what packages you need to build Orca Electron. Discover required runtime libraries, development tools, and optional dependencies for this React UI application.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: how-to-guide
- Published: 2026-05-25

---

**Building the Orca Electron application requires pnpm, Node.js, and three categories of dependencies defined in the root [`package.json`](https://github.com/stablyai/orca/blob/main/package.json): runtime libraries for the React UI and Monaco editor, development tools including TypeScript and electron-builder, and optional platform-specific Sherpa-ONNX binaries for speech recognition.**

Orca is a TypeScript-based Electron application developed by StablyAI that integrates a React frontend with native system capabilities like terminals and SQLite databases. Building the application from source requires installing runtime dependencies for the editor and terminal components alongside specialized build tools that handle TypeScript compilation and Electron packaging.

## Runtime Dependencies Required for Building Orca

The runtime dependencies power the application's core functionality once compiled. These packages are installed into the `node_modules` directory and bundled into the final Electron executable by `electron-vite`.

### UI Framework and Editor Components

The interface relies on **React** combined with specialized editing libraries. Key packages include `@monaco-editor/react` and `monaco-editor` for code editing, `@tiptap/*` for rich text processing, and `@dnd-kit/*` for drag-and-drop interactions. Styling is handled by `tailwindcss`, `tailwind-merge`, and `tw-animate-css`, while `lucide-react` and `radix-ui` provide the component iconography and primitives. Additional utilities include `clsx`, `cmdk`, and `sonner` for UI interactions.

### Terminal and Database Integration

Native system integration requires platform-specific modules. The terminal functionality uses `@xterm/*` for the frontend terminal emulator paired with `node-pty` for creating pseudoterminals. Database operations rely on `better-sqlite3` for local storage, while `ssh2` enables secure shell connections. The `simple-git` package provides Git integration for repository management, and `agent-browser` handles browser automation tasks.

### Cryptography and Real-Time Communication

Security-sensitive features depend on `tweetnacl` for encryption and `dompurify` for HTML sanitization. Real-time communication uses `ws` for WebSocket connections. Additional utilities include `zod` for schema validation, `yaml` for configuration parsing, `zustand` for state management, and `posthog-node` for analytics. The `electron-updater` package handles automatic updates in the distributed application.

## Development and Build Toolchain

Dev dependencies handle TypeScript compilation, bundling, and testing without being included in the final application binary stored in `out/` or `dist/`.

### Type Checking and Linting

The build process starts with type validation using the configurations in [`config/tsconfig.node.json`](https://github.com/stablyai/orca/blob/main/config/tsconfig.node.json), [`config/tsconfig.cli.json`](https://github.com/stablyai/orca/blob/main/config/tsconfig.cli.json), and the web-specific TypeScript config. The toolchain includes `typescript`, `oxlint` for fast linting, and `oxfmt` for code formatting. `husky` and `lint-staged` manage pre-commit hooks to ensure code quality before commits reach the repository.

### Bundling and Electron Packaging

**Vite** serves as the primary bundler through `electron-vite` and `@vitejs/plugin-react`. The `electron-builder` package (configured in `config/electron-builder.config.cjs`) creates platform-specific installers, while `@electron/rebuild` compiles native modules like `better-sqlite3` against the correct Electron Node.js version. The `@electron-toolkit/tsconfig` and `@electron-toolkit/utils` provide standardized Electron development utilities.

### Testing Infrastructure

Quality assurance relies on `vitest` for unit testing and `@playwright/test` alongside `@stablyai/playwright-test` for end-to-end testing of the Electron application. The `@types/*` packages (including `@types/better-sqlite3`, `@types/node`, `@types/ssh2`, and `@types/ws`) provide TypeScript definitions for native modules.

## Optional Native Binaries (Sherpa-ONNX)

Speech recognition capabilities require platform-specific native binaries that are not included in the base installation. The `sherpa-onnx` package requires separate wheel installations for the target platform:

- `sherpa-onnx-darwin-arm64` (Apple Silicon macOS)
- `sherpa-onnx-darwin-x64` (Intel macOS)
- `sherpa-onnx-linux-arm64` (ARM Linux)
- `sherpa-onnx-linux-x64` (x86 Linux)
- `sherpa-onnx-win-x64` (Windows x64)

These binaries are only installed when building for the specific target platform and are referenced by the main `sherpa-onnx` runtime dependency.

## How to Install Orca Build Dependencies

All dependencies are installed through pnpm using the root [`package.json`](https://github.com/stablyai/orca/blob/main/package.json) located at the top level of the repository.

Clone the repository and install all runtime and development packages:

```bash
git clone https://github.com/stablyai/orca.git
cd orca
pnpm install

```

This command downloads all required Node modules, including the Electron runtime, React libraries, and build tools. The process also triggers `electron-rebuild` to compile native modules against the correct Electron version.

## Building Orca from Source

The [`package.json`](https://github.com/stablyai/orca/blob/main/package.json) scripts define a specific build sequence that compiles TypeScript, bundles assets, and packages the application for distribution.

Build the full application:

```bash
pnpm run build

```

This executes a chain of scripts defined in [`package.json`](https://github.com/stablyai/orca/blob/main/package.json):
1. `pnpm run typecheck` – Validates TypeScript across Node, CLI, and web targets using the configs in `config/`.
2. `pnpm run build:relay` – Compiles the Relay server components.
3. `pnpm run build:computer-macos` – Builds the native macOS computer agent.
4. `pnpm run build:electron-vite` – Bundles the renderer process with Vite.
5. `pnpm run build:web` – Generates the web-only build assets.
6. `pnpm run build:cli` – Compiles the command-line interface entry point.

Run the development server with hot-reload:

```bash
pnpm run dev

```

For the web-only version without Electron:

```bash
pnpm run dev:web

```

Package for distribution using `electron-builder`:

```bash

# macOS .dmg

pnpm run build:mac

# Windows installer

pnpm run build:win

# Linux package

pnpm run build:linux

```

These scripts invoke `electron-builder` using the configuration defined in `config/electron-builder.config.cjs`.

## Critical Configuration Files

Understanding the build system requires familiarity with these specific files in the repository:

- **[`package.json`](https://github.com/stablyai/orca/blob/main/package.json)** – Declares all runtime and dev dependencies; defines the npm scripts that orchestrate the build pipeline.
- **`config/electron-builder.config.cjs`** – Configures `electron-builder` targets, code signing, and installer formats for macOS, Windows, and Linux.
- **[`config/tsconfig.node.json`](https://github.com/stablyai/orca/blob/main/config/tsconfig.node.json)** – TypeScript configuration for the Electron main process and Node-specific code.
- **`src/renderer/`** – Contains React components, Tailwind styles, and shadcn UI primitives compiled by Vite.
- **`src/main/`** – Houses the Electron main process code responsible for window management and IPC.
- **`config/scripts/`** – Helper scripts for type-checking, native dependency rebuilding, and environment verification.

## Summary

- Orca requires **runtime dependencies** for React, Monaco Editor, SQLite (`better-sqlite3`), and terminal emulation (`node-pty`, `@xterm/*`) bundled into the final Electron app.
- **Development dependencies** include TypeScript, Vite, `electron-builder`, and testing frameworks like Vitest and Playwright.
- **Optional Sherpa-ONNX binaries** provide speech recognition but must be installed separately for each target platform (Darwin ARM64/x64, Linux ARM64/x64, Windows x64).
- All packages are declared in the root [`package.json`](https://github.com/stablyai/orca/blob/main/package.json) and installed via `pnpm install`.
- The build process runs through `pnpm run build`, which executes type checking, Relay compilation, and Vite bundling before `electron-builder` packages the distributables.

## Frequently Asked Questions

### What package manager does Orca require?

Orca uses **pnpm** exclusively. The build scripts and dependency tree in [`package.json`](https://github.com/stablyai/orca/blob/main/package.json) are optimized for pnpm's workspace and caching behavior. While npm or yarn might work, pnpm is the officially supported and tested package manager for this repository. Using pnpm ensures that peer dependencies like React are correctly deduplicated and that native modules are properly linked.

### Why does the build require platform-specific Sherpa-ONNX packages?

The Sherpa-ONNX libraries provide **native speech recognition capabilities** that rely on platform-specific compiled binaries. The `sherpa-onnx-darwin-arm64`, `sherpa-onnx-linux-x64`, and similar packages contain pre-compiled wheels for the C++ backend. These are marked as optional dependencies and are only required if you need voice input functionality in the final application; the build will succeed without them if speech features are disabled.

### Which Node.js version is compatible with Orca's build dependencies?

Orca targets modern Node.js versions compatible with **Electron's current requirements**, typically the Active LTS version. The `@electron/rebuild` package ensures that native modules like `better-sqlite3` and `node-pty` are compiled against the specific Node.js version embedded within the Electron runtime defined in the dev dependencies. You should use the Node.js version specified in the engine requirements of the [`package.json`](https://github.com/stablyai/orca/blob/main/package.json) file.

### What is the difference between `pnpm run build` and `pnpm run build:electron-vite`?

The `pnpm run build` command is a **meta-script** that executes the entire pipeline: type checking (`typecheck`), Relay compilation (`build:relay`), native agent building (`build:computer-macos`), and finally the Vite bundling. The `pnpm run build:electron-vite` command specifically **bundles only the Electron renderer and preload scripts** using Vite without running the full type-checking or native compilation steps. Use `build:electron-vite` for faster iteration during UI development, and `build` for production releases.