OpenWork Build Process: How to Compile the Desktop App and Web UI from Source

The OpenWork build process uses pnpm workspaces to compile an Electron desktop application and a Vite-based web UI through a Node.js orchestration script that handles side-car binaries, server bundling, and platform-specific packaging.

The OpenWork repository by different-ai is a monorepo managed with pnpm workspaces that produces both a cross-platform desktop application and a deployable web interface. Understanding the build process for OpenWork requires navigating the workspace structure, environment-specific configurations, and the Node.js scripts that coordinate compilation across the @openwork/desktop and @openwork/app packages on the dev branch.

Build Pipeline Architecture

The build process follows a six-phase pipeline orchestrated from the repository root. Each phase delegates to specific packages within the workspace, using environment variables to distinguish between desktop and web targets.

Phase 1: Workspace Initialization

The entry point resides in the root package.json, where the build script executes node scripts/build.mjs. This Node helper immediately delegates to the desktop package using pnpm --filter @openwork/desktop build, serving as the central hub for all compilation tasks.

Phase 2: Desktop Application Compilation

The script apps/desktop/scripts/electron-build.mjs performs the heavy lifting for the Electron application. According to the source code, this script:

• Prepares side-car binaries and helper scripts for the desktop environment
• Compiles the openwork-server into JavaScript for bundling
• Builds the web UI (@openwork/app) with OPENWORK_ELECTRON_BUILD=1 to ensure assets use relative paths suitable for ASAR packaging
• Patches the server bundle to resolve constants.json correctly inside the packaged ASAR archive
• Copies the compiled server into the Electron resources directory
• Type-checks all Electron entry files (*.mjs)

Phase 3: Application Packaging

After compilation, electron-builder creates distributable bundles for macOS, Windows, and Linux. The configuration is defined in apps/desktop/electron-builder.yml, with package scripts like package:electron, package:electron:cloud, and package:electron:enterprise setting appropriate environment contexts before invoking the builder.

Phase 4: Web UI Standalone Build

For server deployment, the @openwork/app package runs Vite to produce static assets in apps/app/dist. The build:web script sets VITE_OPENWORK_DEPLOYMENT=web and VITE_DEN_REQUIRE_SIGNIN=1, forcing authentication flows suitable for hosted environments rather than local desktop usage.

Phase 5: Enterprise Ancillary Builds

Optional components include the Den web control plane (@openwork-ee/den-web) and enterprise mock lab diagnostics. These reside in ee/apps/* and are invoked via top-level shortcuts pnpm run build:web and pnpm run build:ui.

Phase 6: Verification

Post-build validation uses pnpm run typecheck for the web UI and pnpm run check:electron for the desktop bridge, ensuring type safety across the generated artifacts before distribution.

Key Build Scripts and Configuration Files

Understanding the build process for OpenWork requires familiarity with these specific files:

• scripts/build.mjs: The top-level orchestrator that delegates to the desktop package
• apps/desktop/scripts/electron-build.mjs: Core build logic handling server compilation, side-car preparation, and ASAR patching
• apps/desktop/package.json: Defines desktop-specific scripts including dev, build, and package:* variants for different distribution channels
• apps/app/package.json: Contains Vite-based build scripts for the renderer process and standalone web deployment
• electron-builder.yml: Configuration for cross-platform packaging, signing, and ASAR exclusions

Environment Variables and Build Contexts

The build process uses specific environment variables to toggle between targets:

• OPENWORK_ELECTRON_BUILD=1: Set during desktop builds to emit assets with relative paths suitable for ASAR packaging
• VITE_OPENWORK_DEPLOYMENT=web: Configures the UI for standalone web deployment rather than Electron renderer
• VITE_DEN_REQUIRE_SIGNIN=1: Forces authentication requirements in hosted web deployments

Practical Build Commands

Execute these commands from the repository root using pnpm version 11 (as declared in package.json):

# Install dependencies across the monorepo

pnpm install

# Full workspace build (desktop + UI compilation)

pnpm build

# Package signed macOS application bundle

pnpm run package:electron

# Build standalone web UI for server deployment

pnpm run build:web

# Type-check Electron bridge files

pnpm run check:electron

# Type-check web UI components

pnpm run typecheck

Summary

• The OpenWork build process starts with pnpm build at the root, which triggers scripts/build.mjs to orchestrate the workspace compilation.
• Desktop builds use apps/desktop/scripts/electron-build.mjs to compile the server, prepare side-car binaries, patch ASAR resources for constants.json resolution, and bundle the Electron application.
• Web UI builds rely on Vite within @openwork/app, using environment variables like VITE_OPENWORK_DEPLOYMENT=web to distinguish between Electron renderer and standalone deployment modes.
• Packaging is handled by electron-builder via scripts defined in apps/desktop/package.json, supporting macOS, Windows, and Linux targets through electron-builder.yml configurations.
• Verification steps include type-checking scripts that ensure the integrity of the compiled artifacts across both desktop and web targets.

Frequently Asked Questions

What tools are required to build OpenWork from source?

You need pnpm version 11 (specified in the root package.json), Node.js, and the standard OpenWork repository checked out from the dev branch. The build process relies on pnpm workspaces to manage dependencies across the @openwork/desktop, @openwork/app, and enterprise packages located in ee/apps/*.

How does the desktop build handle the OpenWork server?

During the desktop build phase, apps/desktop/scripts/electron-build.mjs compiles the openwork-server into JavaScript and copies it into the Electron resources directory. The script also patches the server bundle to correctly resolve constants.json paths inside the packaged ASAR archive, ensuring the server can access its configuration at runtime when running inside the Electron context.

What is the difference between pnpm build and pnpm run build:web?

pnpm build (or pnpm run build) triggers the full desktop build pipeline via scripts/build.mjs, compiling both the Electron application and its embedded UI with OPENWORK_ELECTRON_BUILD=1. In contrast, pnpm run build:web invokes Vite directly in @openwork/app to produce a standalone static site for browser deployment, setting VITE_OPENWORK_DEPLOYMENT=web to adjust routing and authentication behavior for hosted environments.

Where are the electron-builder configurations stored?

The packaging configurations reside in apps/desktop/electron-builder.yml (and variant files for cloud/enterprise editions). These YAML files define platform-specific settings, signing certificates, and ASAR exclusions used when running pnpm run package:electron or its variant scripts defined in apps/desktop/package.json.

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