Minimum Node.js and pnpm Versions Required for Deploying OpenMAIC

OpenMAIC requires Node.js ≥22.19.0 and pnpm ≥10 to ensure compatibility with modern ES modules, top-level await, and workspace features used throughout the codebase.

Deploying the THU-MAIC/OpenMAIC repository demands specific runtime prerequisites to guarantee stable operation. Understanding the minimum Node.js and pnpm versions required for deploying OpenMAIC prevents installation failures and runtime errors when setting up this modern application stack. The constraints are explicitly defined in the project's package.json and documented in the README prerequisites section.

Node.js Version Requirements

Minimum Version Specification

In the root package.json at lines 7-8, the engines field explicitly declares:

"engines": {
  "node": ">=22.19.0"
}

This requirement is reiterated in the Prerequisites section of README.md (lines 108-110). Node.js 22.19.0 or newer is mandatory because the codebase relies on features introduced in the Node.js 22.x series, including top-level await and enhanced ES module support.

pnpm Version Requirements

Minimum Version Specification

The project requires pnpm version 10 or higher. This constraint appears in the README.md prerequisites and is enforced through the packageManager field in package.json (lines 209-210), which currently specifies:

"packageManager": "pnpm@10.28.0"

While the lockfile pins 10.28.0, any stable 10.x release satisfies the minimum requirement. The pnpm 10.x line introduced critical workspace handling improvements that OpenMAIC's monorepo structure depends on.

Verifying Your Environment

Before running installation commands, verify your tooling matches these minimums:

# Check Node.js version (must be ≥22.19.0)

node -v

# Expected: v22.19.0 or higher

# Check pnpm version (must be ≥10)

pnpm -v

# Expected: 10.28.0 or higher

# Install dependencies only after confirming versions

pnpm install

If either check returns an older version, upgrade Node.js using nvm or your system package manager, and update pnpm via npm i -g pnpm@latest.

Why These Minimums Exist

Using older versions triggers explicit failures during installation or runtime. The enforcement occurs because:

• Node.js 22 features: The application code utilizes syntax and APIs unavailable in Node.js 20 or earlier
• pnpm workspace compatibility: The repository relies on pnpm 10's enhanced workspace protocol handling for internal package linking

Summary

• Node.js: Version 22.19.0 or newer, specified in package.json under the engines field (lines 7-8)
• pnpm: Version 10.x or newer, declared via packageManager in package.json (lines 209-210) and documented in README.md (lines 108-110)
• Verification: Use node -v and pnpm -v before running pnpm install
• Upgrade path: Use nvm for Node.js and npm i -g pnpm@latest for pnpm if versions are insufficient

Frequently Asked Questions

What happens if I use Node.js 20 instead of 22.19.0?

The installation scripts and runtime checks will fail. OpenMAIC relies on Node.js 22-specific features such as top-level await and enhanced ES module resolution that are not available in version 20. You must upgrade to Node.js 22.19.0 or later to deploy successfully.

Can I use pnpm 9.x with OpenMAIC?

No. While pnpm 9.x might install dependencies, the project explicitly requires pnpm ≥10 as documented in the README.md prerequisites and enforced through the packageManager field in package.json. Version 10 introduced workspace handling changes that the monorepo structure depends on.

Where are the version requirements documented in the source code?

The Node.js requirement appears in the root package.json under the engines field (lines 7-8) and in README.md (lines 108-110). The pnpm requirement is listed in the same README section and enforced via the packageManager entry in package.json (lines 209-210).

Is there a maximum version limit for Node.js or pnpm?

No maximum version is specified. Any stable release newer than the minimums—such as Node.js 22.x or 23.x, and pnpm 10.x or 11.x—should work correctly. The constraints define minimum floors, not ceilings.

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