Orca Build Dependencies: Complete Guide to Required Packages

Building the Orca Electron application requires pnpm, Node.js, and three categories of dependencies defined in the root 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, 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 located at the top level of the repository.

Clone the repository and install all runtime and development packages:

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 scripts define a specific build sequence that compiles TypeScript, bundles assets, and packages the application for distribution.

Build the full application:

pnpm run build

This executes a chain of scripts defined in 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:

pnpm run dev

For the web-only version without Electron:

pnpm run dev:web

Package for distribution using electron-builder:

# 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 – 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 – 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 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 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 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.

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