Node.js Management

Corral manages Node.js installations for you — download versions on demand, pin them per project, and run commands with the right version automatically. No need for nvm, fnm, or any other version manager.

Version Resolution

When starting a project or running a command, Corral resolves the Node.js version in this order:

Priority	Source	Example
1	--node-version flag or CORRAL_NODE_VERSION env var	corral exec --node-version 22 node -v
2	Per-project Corral setting	corral project set my-worker node-version 22
3	.node-version file in the project directory	22.3.0
4	.nvmrc file in the project directory	22
5	App-wide default version	corral settings set default-node-version 22
6	Latest installed version	Whatever's newest in ~/.corral/node/
7	Auto-install latest LTS	Downloads automatically as a last resort

The first match wins. This means a .node-version file in your project will override the app-wide default, and an explicit flag overrides everything.

Installing Node.js Versions

Install a specific version:

corral node install 22.3.0

Install the latest in a major version:

corral node install 22

Install the latest LTS:

corral node install lts

Corral downloads official binaries from nodejs.org and verifies their SHA256 checksums. Installations are stored in ~/.corral/node/v{version}/.

List installed versions:

corral node list

See what's available:

# All versions (20 most recent)
corral node available

# LTS versions only
corral node available --lts

Remove a version:

corral node remove 22.3.0

Version Specification

You can specify versions in several formats:

Format	Example	Resolves To
Exact	22.3.0 or v22.3.0	That exact version
Major.minor	22.3	Latest patch of 22.3.x
Major	22	Latest version of 22.x.x
LTS	lts or lts/*	Latest LTS release

Per-Project Versions

Option 1: Corral setting

corral project set my-worker node-version 22

Option 2: .node-version file in your project directory:

22.3.0

Option 3: .nvmrc file in your project directory:

22

Corral respects these files automatically. If you're already using .node-version or .nvmrc with another version manager, Corral will honor them without any extra configuration.

Setting a Global Default

corral settings set default-node-version 22

This version is used when no project-specific version is configured. Clear it with:

corral settings set default-node-version none

Running Commands PRO

Pro Feature

Command execution with auto-resolved Node requires Corral Pro. Learn more →

Run any command using the resolved Node.js version for the current directory:

corral exec node -v
corral exec npx vitest

Shorthand commands for npm and npx:

corral npm install
corral npx wrangler deploy

Override the version for a single command:

corral exec --node-version 20 node -v

Or via environment variable:

CORRAL_NODE_VERSION=20 corral exec node -v

TIP

corral exec replaces the current process rather than wrapping it. This means there's no overhead — signals, exit codes, and stdio work exactly as if you ran the command directly.

Shell Shims PRO

Pro Feature

Shell shims require Corral Pro. Learn more →

For seamless integration with your terminal workflow, install shell shims that make node, npm, npx, and cpm automatically use Corral:

corral install-shims

This creates lightweight scripts in ~/.corral/bin/ that delegate to corral exec. To add them to your PATH:

corral install-shims --patch-profile

This adds ~/.corral/bin to your PATH in your shell profile (~/.zshrc, ~/.bashrc, etc.). After reloading your shell:

# Uses the Corral-resolved version automatically
node -v
npm install
npx vitest

# cpm is a shorthand for `corral pm` — use any package manager syntax
cpm install
cpm add -D vitest

To remove the shims:

corral uninstall-shims

You can also install and manage shims from the macOS app's Node.js Manager.