How to Use the Build Script in OpenWork: A Complete Guide

Run pnpm run build at the repository root to compile the OpenWork desktop client, which delegates to scripts/build.mjs and ultimately executes the Electron build defined in apps/desktop/package.json.

The different-ai/openwork repository uses a centralized build orchestration system to compile its Electron desktop application. The build script in OpenWork serves as the primary entry point for packaging the application, delegating specific compilation tasks to workspace packages while maintaining a clean separation between the root configuration and package-specific logic. Understanding this hierarchy is essential for modifying build behavior or troubleshooting compilation errors.

What the Build Script Does

The root-level build script functions as a thin wrapper that delegates compilation to the desktop package through a filtered workspace command.

Root Package Entry Point

In the repository root package.json, the build command is defined as:

"build": "node scripts/build.mjs"

See [package.json](https://github.com/different-ai/openwork/blob/dev/package.json#L42‑L44) for the exact declaration.

The Desktop Build Delegation

The scripts/build.mjs file contains a simple Node.js script that executes the desktop package's build using pnpm's workspace filtering:

execSync("pnpm --filter @openwork/desktop build", { stdio: "inherit" });

See scripts/build.mjs for the source implementation.

Actual Build Execution

Inside apps/desktop/package.json, the filtered build resolves to:

"build": "node ./scripts/electron-build.mjs"

This script performs the Electron compilation and packaging. See [apps/desktop/package.json](https://github.com/different-ai/openwork/blob/dev/apps/desktop/package.json#L23‑L26) and apps/desktop/scripts/electron-build.mjs for the complete build logic.

Prerequisites

Before running the build script, ensure your environment meets these requirements:

• Node.js ≥ 18 – Required for ES module support and modern Node APIs used throughout the build chain.
• pnpm ≥ 11 – The lockfile specifies pnpm@11.4.0, and the build script explicitly calls pnpm commands.
• Workspace dependencies installed – Run pnpm install at the repository root to install all monorepo dependencies.

Step-by-Step Usage

Follow these steps to execute the build script correctly:

1. Install dependencies at the repository root:

   pnpm install

2. Run the build script:

   pnpm run build

   This invokes scripts/build.mjs, which executes pnpm --filter @openwork/desktop build and streams output via stdio: "inherit".

3. Locate the output – The compiled Electron binaries and application packages are generated in apps/desktop/dist (the exact path is defined by the Electron-builder configuration).

Alternative Build Targets

OpenWork provides granular build scripts for specific components when you do not need the full desktop build:

• build:ui – Compiles only the React UI (@openwork/app)
• build:web – Builds only the Den web server (@openwork-ee/den-web)

# Build only the UI (faster for front-end changes)

pnpm run build:ui

# Build only the backend web services

pnpm run build:web

While npm run build syntax is supported at the root, the underlying scripts require pnpm for workspace filtering.

Summary

• The root build script in package.json points to scripts/build.mjs, which filters and executes the @openwork/desktop package build.
• The desktop build runs node ./scripts/electron-build.mjs as defined in apps/desktop/package.json.
• Compiled binaries output to apps/desktop/dist.
• Alternative scripts build:ui and build:web target specific workspace packages for faster iteration.
• Requires Node.js ≥ 18 and pnpm ≥ 11 (specifically pnpm@11.4.0 per the lockfile).

Frequently Asked Questions

Where does the build script output the compiled application?

The build script outputs Electron binaries to apps/desktop/dist, with the exact structure and naming configured by the Electron-builder settings in the desktop package. This directory contains the packaged application ready for distribution.

Can I use npm instead of pnpm to run the build script?

While npm run build will execute at the root level, the underlying scripts/build.mjs explicitly calls pnpm --filter, making pnpm effectively required for the build process to complete successfully. The workspace filtering functionality depends on pnpm's specific implementation.

What Node.js version is required to run the build script?

OpenWork requires Node.js version 18 or higher because the build scripts utilize ES modules (.mjs extensions) and modern Node.js APIs. Attempting to run the build with earlier versions will result in module resolution or syntax errors.

How do I build only the desktop client without other packages?

The default pnpm run build already targets only the desktop client through the --filter @openwork/desktop flag in scripts/build.mjs. If you need to build other specific components individually, use pnpm run build:ui for the React interface or pnpm run build:web for the Deno-based web services.

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