Node.js Requirements for Caveman Installation: Complete Version Guide

Caveman requires Node.js version 18 or higher, enforced by runtime checks in the installer script.

The JuliusBrussee/caveman repository mandates Node.js 18+ across its entire codebase to ensure modern JavaScript compatibility. These Node.js requirements for Caveman installation are enforced at multiple validation points—from package metadata to runtime guards—preventing execution on unsupported environments. Verify your environment meets this threshold before executing the install command to avoid mid-process failures.

Where Node.js Requirements Are Declared

Caveman specifies its engine dependency in two critical files that enforce the version constraint before any code execution.

Package.json Engine Field

In package.json, the engines field explicitly declares "node": ">=18" as a hard dependency. This metadata serves as the canonical source for Node.js requirements for Caveman installation, signaling compatibility requirements to package managers and deployment platforms.

Install Shell Script Validation

The install.sh shell script performs early validation before delegating to the Node installer. It verifies that the node binary exists in your PATH and confirms the major version is at least 18, aborting immediately with an error message if the requirement is not met.

Runtime Version Enforcement

Beyond static declarations, Caveman implements active runtime guards to prevent installation on incompatible versions.

The checkNodeVersion() Function

Inside bin/install.js, the checkNodeVersion() function implements strict runtime validation. This function parses the current Node.js process version and terminates the installation with an error code if the detected version is below 18.

Legacy Hook Script

The repository also includes src/hooks/install.sh as a legacy hook script, which remains referenced by the installer for backwards compatibility while maintaining the same version requirements.

Verifying Your Node.js Environment

Before initiating installation, confirm your Node version meets Caveman's requirements:

# Check current Node.js version

node -v

# Expected output: v18.x.x or higher

If your version is below 18, upgrade using nvm or your system package manager before proceeding.

Installing Caveman

Once Node.js 18+ is confirmed, run the official installer:

# One-line installation command

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

Because npx ships with Node.js 18 and higher, no additional npm packages are required for the installation process.

Summary

• Caveman strictly requires Node.js 18 or higher according to the JuliusBrussee/caveman source code
• Requirements are declared in package.json under the engines field with the constraint "node": ">=18"
• install.sh validates the Node version exists and is ≥ 18 before executing the installer
• bin/install.js contains the checkNodeVersion() function that enforces this constraint at runtime
• Upgrade older Node versions via nvm or your system package manager before attempting installation

Frequently Asked Questions

What is the minimum Node.js version for Caveman?

Caveman requires Node.js version 18 or higher. This requirement is hardcoded in the package.json engines field and enforced by the checkNodeVersion() function in bin/install.js, which aborts the process if the runtime version is insufficient.

How does Caveman check the Node version during installation?

The installation process validates Node.js in two stages: first, the install.sh shell script verifies that the node command exists and that its major version is at least 18. Then, bin/install.js executes the checkNodeVersion() function to perform a secondary runtime check before continuing with package operations.

Will Caveman install on Node.js 16 or 17?

No. If you attempt to install Caveman on Node.js 16, 17, or earlier, the installer will abort with an error message. Both the shell installer and the Node.js validation function explicitly reject versions below 18, preventing partial or broken installations.

Do I need to install npm separately for Caveman?

No additional npm packages are required for installation. Since npx ships with Node.js 18 and higher, the Caveman installer uses the built-in npx capabilities to complete the setup without requiring separate npm dependencies or global package installations.

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