Maximum Node.js Version Supported for Native Packages in Feynman: v25.x Compatibility

Feynman explicitly caps Node.js support at versions below 26.0.0, making any 25.x release—such as v25.9.0—the maximum supported version for native packages.

The Feynman repository (advaitpaliwal/feynman) defines strict Node.js engine requirements to ensure binary compatibility with native dependencies. By analyzing the source code, we can see exactly which versions are permitted and how the project enforces these constraints during installation.

Understanding the Maximum Node.js Version Constraint in package.json

In the repository root, the package.json file declares the supported runtime range within the engines field:

"engines": {
  "node": ">=22.22.0 <26"
}

This semantic versioning range establishes two boundaries:

• Minimum: Version 22.22.0 or higher
• Maximum: Strictly less than 26.0.0 (any 25.x release)

Consequently, the maximum Node.js version supported for native packages is the highest 25.x release available (e.g., v25.9.0). Native dependencies—such as esbuild or compiled C/C++ add-ons—are compiled against specific Node ABIs (Application Binary Interfaces). The <26 upper bound prevents ABI mismatches that would otherwise break these binary-linked modules when Node 26 introduces potential breaking changes.

How Feynman Enforces Node.js Compatibility

The repository employs an active enforcement mechanism that runs before installation completes.

Pre-Install Verification with check-node-version.mjs

Located at scripts/check-node-version.mjs, this helper script executes during the preinstall npm hook. It reads the engines.node range from package.json and validates the current runtime version using the semver library. If process.version falls outside the >=22.22.0 <26 range, the script aborts installation with a descriptive error, preventing users from building native binaries on incompatible Node versions.

Build Process Protection

The scripts/build-native-bundle.mjs script handles the compilation of native bundles. By relying on the same version constraints enforced during pre-installation, this build script ensures that native modules are only compiled against supported Node ABIs, eliminating runtime crashes caused by binary incompatibilities.

Checking Your Node.js Version Before Installation

Before running Feynman, verify your Node.js version using nvm (Node Version Manager):

# Install and activate a supported version

nvm install 25
nvm use 25

# Confirm the active version

node -v

# Output: v25.x.x

# Proceed with installation

npm install -g feynman

If your current version is outside the supported range, the preinstall script will terminate the installation process before any native compilation begins.

Programmatic Version Validation

You can mirror Feynman's internal validation logic in your own scripts to check compatibility programmatically:

import { readFileSync } from 'fs';
import semver from 'semver';

const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
const requiredRange = pkg.engines.node;    // ">=22.22.0 <26"
const currentVersion = process.version;    // e.g., "v25.5.0"

if (!semver.satisfies(currentVersion, requiredRange)) {
  console.error(
    `Unsupported Node version ${currentVersion}. Required: ${requiredRange}`
  );
  process.exit(1);
}

console.log('Node.js version is compatible with Feynman native packages.');

This approach uses the same semver.satisfies() check implemented in scripts/check-node-version.mjs, ensuring your environment matches the requirements defined in the Feynman source code.

Summary

• Maximum supported version: Any Node.js 25.x release (e.g., v25.9.0), as defined by the <26 upper bound in package.json.
• Minimum supported version: Node.js v22.22.0 or higher.
• Enforcement mechanism: The scripts/check-node-version.mjs script runs during preinstall to block incompatible versions.
• Native package protection: The version ceiling prevents ABI mismatches with compiled binary dependencies like esbuild.
• Build integration: scripts/build-native-bundle.mjs relies on these constraints to ensure successful native compilation.

Frequently Asked Questions

What is the highest Node.js version I can use with Feynman?

You can use any Node.js version up to the latest 25.x release (such as v25.9.0). The package.json explicitly defines the upper bound as <26, meaning version 26.0.0 and higher are not supported.

Why does Feynman cap Node.js support below version 26?

Native packages contain binary components compiled against specific Node ABIs. Node 26 may introduce breaking ABI changes that would render existing native binaries incompatible. By capping support at <26, Feynman guarantees that native modules like esbuild maintain binary compatibility with the runtime.

What happens if I try to install Feynman with Node.js 26 or higher?

The installation will fail during the preinstall phase. The scripts/check-node-version.mjs script detects the version mismatch, logs an error message specifying the required range (>=22.22.0 <26), and exits with code 1 before any native compilation or package installation occurs.

How do I switch to a supported Node.js version using nvm?

Run nvm install 25 followed by nvm use 25 to install and activate the latest Node.js 25.x version. Verify the switch with node -v, which should display a version number between v22.22.0 and v25.x.x, ensuring compatibility with Feynman's native package requirements.

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