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

> Build OpenClaude easily by understanding its requirements. Learn about the Node.js version, Bun setup, and TypeScript configuration needed for successful compilation.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: getting-started
- Published: 2026-09-08

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/package.json):

```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:

```bash

# 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`:

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

```

Type checking executes via `tsc --noEmit`, configured in [`tsconfig.json`](https://github.com/Gitlawb/openclaude/blob/main/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:

```bash

# 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`](https://github.com/Gitlawb/openclaude/blob/main/package.json) | Declares Node engine constraint, scripts, and dependency versions |
| `.bun-version` | Pins exact Bun version for reproducible builds |
| [`tsconfig.json`](https://github.com/Gitlawb/openclaude/blob/main/tsconfig.json) | TypeScript compiler configuration and strictness rules |
| [`scripts/build.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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.