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

> Discover the maximum Node.js version compatible with native packages in Feynman. Ensure smooth integration by using Node.js v25.x releases for optimal performance.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: api-reference
- Published: 2026-09-08

---

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

In the repository root, the [`package.json`](https://github.com/advaitpaliwal/feynman/blob/main/package.json) file declares the supported runtime range within the **`engines`** field:

```json
"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`](https://github.com/advaitpaliwal/feynman/blob/main/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):

```bash

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

```javascript
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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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.