OpenClaude Build Requirements: Node.js Version, Bun, and TypeScript Setup

You need Node.js ≥ 22.0.0, Bun (pinned version), and TypeScript 5.9 to build and run OpenClaude.

OpenClaude is a TypeScript-based CLI tool that combines Node.js as its runtime with Bun for package management and build orchestration. Understanding these build requirements ensures a smooth local development setup and prevents compatibility issues during compilation.

Node.js Version Requirement

OpenClaude requires Node.js ≥ 22.0.0, as declared in the engines field of package.json:

// package.json (lines 84-86)
"engines": {
  "node": ">=22.0.0"
}

This version requirement is non-negotiable. The codebase relies on native withResolvers utilities and other modern Node APIs introduced in Node 22. Attempting to build with Node 20 or earlier will fail due to missing runtime features.

While the documentation in web/src/pages/docs/installation.astro mentions "Node ≥ 20" as a general guideline for older releases, the current engines field strictly enforces Node 22+.

Bun for Build and Package Management

Bun serves as the primary toolchain for OpenClaude. All development scripts invoke bun explicitly:

• bun install — dependency installation
• bun run build — compilation pipeline
• bun test — test execution

The repository pins a specific Bun version via the .bun-version file, ensuring CI reproducibility:

# Check the pinned version

cat .bun-version

# → 1.1.30 (example)

This version must match your local Bun installation to guarantee consistent builds.

TypeScript Configuration

TypeScript 5.9.3 is locked in devDependencies:

// package.json (lines 151-153)
"devDependencies": {
  "typescript": "5.9.3"
}

Type checking executes via tsc --noEmit, configured in tsconfig.json. The TypeScript compiler handles strict null checks and ES2022 target output used throughout the source.

Complete Build Setup

Follow these steps to satisfy all OpenClaude build requirements:

# 1. Install Node.js 22+ (using nvm)

nvm install 22
nvm use 22
node --version  # verify: v22.x.x

# 2. Install Bun matching the pinned version

curl -fsSL https://bun.sh/install | bash -s "bun-$(cat .bun-version)"
bun --version  # verify against .bun-version contents

# 3. Install dependencies and build

bun install
bun run build

# 4. Verify the built CLI

node dist/cli.mjs --version

Platform Support

OpenClaude builds successfully on:

• Linux — primary development platform
• macOS — Intel and Apple Silicon
• Windows — via standard Node.js distributions

The web and vscode-extension directories contain additional platform-specific guidance in their respective documentation.

Key Source Files

These files define and enforce the build environment:

File	Purpose
package.json	Declares Node engine constraint, scripts, and dependency versions
.bun-version	Pins exact Bun version for reproducible builds
tsconfig.json	TypeScript compiler configuration and strictness rules
scripts/build.ts	Build pipeline entry point invoked by bun run build
bin/openclaude	Executable stub used after successful compilation

Summary

• Node.js ≥ 22.0.0 is mandatory for modern runtime APIs
• Bun is required for all build, test, and package operations
• TypeScript 5.9 is locked and installed automatically via bun install
• Platform support includes Linux, macOS, and Windows
• Version pinning via .bun-version ensures CI consistency

Frequently Asked Questions

Can I use npm or yarn instead of Bun?

No. The build scripts in package.json explicitly invoke bun commands, and the project relies on Bun's lockfile (bun.lock) for dependency resolution. Substituting npm or yarn will break the build pipeline.

What happens if I use Node 20 instead of Node 22?

The build will fail at runtime. OpenClaude uses Promise.withResolvers and other Node 22-native APIs that do not exist in earlier versions. The engines field in package.json will also emit a warning during bun install.

Where is the Bun version requirement documented?

The .bun-version file in the repository root pins the exact version. This file is read by CI systems and should guide your local Bun installation. Check it with cat .bun-version after cloning.

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