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

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

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

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

To remove the shims:

corral uninstall-shims

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