# OpenShip Node.js Requirements: Runtime Versions and Compatibility Guide

> Discover the essential Node.js runtime versions and Bun package manager requirements for the OpenShip project. Ensure compatibility for smooth development.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: runtime-requirements
- Published: 2026-07-23

---

**OpenShip requires Node.js version 22.0.0 or higher and uses Bun 1.3.10 as its specified package manager.**

The `oblien/openship` repository is a modern JavaScript monorepo that enforces strict runtime constraints to ensure consistent builds across its workspaces. Understanding these OpenShip Node.js requirements is essential before attempting to build the UI, API, or CLI components.

## Node.js Engine Requirements

OpenShip explicitly targets modern Node.js runtimes. In the root [`package.json`](https://github.com/oblien/openship/blob/main/package.json), the `engines` field declares the minimum version constraint:

```json
"engines": {
  "node": ">=22.0.0"
}

```

This requirement is enforced across all workspaces, including `apps/*` and `packages/*` directories. None of the individual workspace [`package.json`](https://github.com/oblien/openship/blob/main/package.json) files override this constraint, meaning the Node.js ≥ 22.0.0 requirement is global and non-negotiable for the entire project.

If your environment runs an older Node version, installation scripts will fail with an `EBADENGINE` error. Using a version manager like `nvm`, `fnm`, or `asdf` is recommended to switch between Node versions per project.

## Bun Package Manager Version

While Node.js serves as the execution runtime, OpenShip uses **Bun** as its development toolchain. The exact version is pinned in the `packageManager` field at the repository root:

```json
"packageManager": "bun@1.3.10"

```

This pinning ensures deterministic behavior for all development scripts (e.g., `bun run build`). Note that Bun is strictly a build and development tool in this context; the production runtime still relies on the Node.js version specified in the engines field.

To verify you are using the correct Bun version:

```bash

# Check current Bun version

bun -v

# If needed, install the specific version via npm

npm install -g bun@1.3.10

```

## Verifying Your Environment

Before running any OpenShip commands, ensure your local environment satisfies the OpenShip Node.js requirements.

**Installing and switching to Node 22 with nvm:**

```bash

# Install Node.js 22 if not present

nvm install 22

# Switch to Node 22 for this session

nvm use 22

# Verify the active version

node -v

# Output: v22.x.x

```

**Running repository scripts with Bun:**

```bash

# Execute a workspace script using the pinned package manager

bun run --cwd apps/desktop make

# Install dependencies across all workspaces

bun install

```

**Optional runtime check:**

You can add a safety guard to your application entry points to fail fast on version mismatch:

```typescript
// src/checkNodeVersion.ts
const required = ">=22.0.0";
if (!require("semver").satisfies(process.version, required)) {
  console.error(`Node ${required} is required – you have ${process.version}`);
  process.exit(1);
}

```

## Workspace Inheritance

The monorepo structure uses **Turborepo** to orchestrate builds across multiple packages. Key files demonstrating the runtime inheritance include:

- **[`package.json`](https://github.com/oblien/openship/blob/main/package.json) (root)** – Declares the global `engines.node` constraint and `packageManager` specification.
- **[`apps/web/package.json`](https://github.com/oblien/openship/blob/main/apps/web/package.json)** – Inherits the Node requirement; contains scripts executed via Bun.
- **[`packages/core/package.json`](https://github.com/oblien/openship/blob/main/packages/core/package.json)** – Core library workspace that respects the top-level engine constraint without override.

Because the constraint is defined at the repository root, all sub-packages automatically inherit the Node.js ≥ 22.0.0 requirement during installation and build phases.

## Summary

- **Node.js ≥ 22.0.0** is mandatory for all OpenShip packages, declared in the root [`package.json`](https://github.com/oblien/openship/blob/main/package.json) `engines` field.
- **Bun 1.3.10** is the pinned package manager for development scripts and build tooling.
- Workspaces in `apps/` and `packages/` inherit these constraints automatically.
- Use `nvm` or similar tools to manage Node versions, and verify with `node -v` before running commands.
- Bun is required for development workflows but Node.js remains the production runtime.

## Frequently Asked Questions

### Can I use a Node.js version newer than 22.0.0 with OpenShip?

Yes. The constraint specifies `>=22.0.0`, meaning any Node.js version 22.0.0 or higher, including newer major versions like 23.x or 24.x, will satisfy the OpenShip Node.js requirements. However, the repository is primarily tested against the Node 22 LTS line.

### Is Bun required to run OpenShip in production?

No. Bun is specified as the `packageManager` for development and build scripts only. The production runtime relies on Node.js. You can install dependencies with Bun during the build process, but the deployed application runs on the Node.js version that meets the `>=22.0.0` engine requirement.

### What happens if I try to install OpenShip with Node.js 20?

The installation will fail with an engine compatibility error. The root [`package.json`](https://github.com/oblien/openship/blob/main/package.json) explicitly blocks Node versions below 22.0.0. You must upgrade your Node runtime using `nvm install 22` or your preferred version manager before attempting `bun install` or `npm install`.

### Where are the runtime requirements defined in the codebase?

The primary definition is in the repository root at [`package.json`](https://github.com/oblien/openship/blob/main/package.json), specifically lines defining the `engines.node` and `packageManager` fields. Individual workspaces like [`apps/web/package.json`](https://github.com/oblien/openship/blob/main/apps/web/package.json) and [`packages/core/package.json`](https://github.com/oblien/openship/blob/main/packages/core/package.json) do not override these settings, ensuring consistent runtime requirements across the entire monorepo.