vx-tool-node

Node.js tool support for the vx universal tool manager.

Overview

vx-tool-node provides Node.js runtime support for vx, enabling automatic installation, version management, and execution of Node.js and npm commands through the vx interface.

Features

Node.js Runtime: Full Node.js runtime support with version management
NPM Integration: Built-in npm package manager support
NPX Support: Package runner functionality for one-time tool execution
Auto-Installation: Automatic download and installation of Node.js versions
Cross-Platform: Windows, macOS, and Linux support
Version Management: Install and switch between multiple Node.js versions
LTS Support: Automatic detection and installation of LTS versions

Supported Commands

Node.js Runtime

# Execute Node.js scripts

vx node script.js

vx node --version

vx node -e "console.log('Hello, World!')"


# Interactive REPL

vx node

NPM Package Manager

# Package management

vx npm install express

vx npm install -g typescript

vx npm uninstall lodash

vx npm update


# Project management

vx npm init

vx npm run dev

vx npm test

vx npm publish


# Information commands

vx npm list

vx npm outdated

vx npm audit

NPX Package Runner

# Run packages without installing

vx npx create-react-app my-app

vx npx typescript --init

vx npx cowsay "Hello from vx!"


# Run specific versions

vx npx typescript@4.9.5 --version

vx npx -p typescript@latest tsc --version

Installation

Through vx CLI

# Install latest LTS version

vx install node


# Install specific version

vx install node@18.17.0

vx install node@20.10.0


# Install latest version

vx install node@latest

Version Constraints

# Semantic version ranges

vx install node@^18.0.0    # Latest 18.x.x

vx install node@~18.17.0   # Latest 18.17.x

vx install node@>=18.0.0   # 18.0.0 or higher

Configuration

Project Configuration (.vx.toml)

[tools]

node = "18.17.0"          # Specific version

# node = "lts"            # Latest LTS

# node = "latest"         # Latest stable

# node = "^18.0.0"        # Version range



[tools.node]

auto_install = true

install_npm = true        # Install npm alongside Node.js

Global Configuration

[tools.node]

default_version = "lts"

auto_install = true

install_timeout = 300

prefer_lts = true



[node.npm]

registry = "https://registry.npmjs.org/"

cache_dir = "~/.npm"

Version Management

Available Versions

The plugin supports all official Node.js releases:

LTS Versions: 18.x, 20.x (recommended for production)
Current Versions: Latest stable releases
Legacy Versions: 16.x and older (limited support)

Version Detection

# List available versions

vx list node


# Show current version

vx node --version


# Show installation path

vx which node

Platform Support

Windows

x64: Full support
x86: Legacy support
ARM64: Windows 11 ARM support

macOS

x64: Intel Mac support
ARM64: Apple Silicon (M1/M2) support
Universal: Automatic architecture detection

Linux

x64: All major distributions
ARM64: ARM-based systems
ARMv7: Raspberry Pi and similar

Integration

With vx-core

use vx_core::{Tool, ToolManager};
use vx_tool_node::NodeTool;

let node_tool = NodeTool::new();
let manager = ToolManager::new();

// Install Node.js
manager.install_tool(&node_tool, "18.17.0").await?;

// Execute Node.js
manager.execute_tool(&node_tool, &["--version"]).await?;

Plugin Registration

use vx_core::{Plugin, PluginManager};
use vx_tool_node::NodePlugin;

let plugin = NodePlugin::new();
let mut manager = PluginManager::new();

manager.register_plugin(Box::new(plugin))?;

Development

Building

cd crates/vx-tool-node

cargo build

Testing

cargo test

Integration Testing

# Test with actual Node.js installation

cargo test --features integration-tests

Implementation Details

Tool Structure

NodeTool: Main Node.js runtime tool
NpmTool: NPM package manager integration
NpxTool: NPX package runner support

Version Resolution

Project Config: Check .vx.toml for version specification
Global Config: Fall back to global default
LTS Detection: Use latest LTS if no version specified
Auto-Install: Download and install if not available

Installation Process

Version Lookup: Query Node.js release API
Download: Fetch appropriate binary/installer
Extraction: Extract to vx tools directory
Verification: Verify installation integrity
NPM Setup: Configure npm if included

Error Handling

Common Errors

Network Issues: Download failures, API timeouts
Permission Errors: Installation directory access
Version Conflicts: Multiple Node.js installations
Corruption: Incomplete or corrupted downloads

Recovery

# Reinstall corrupted version

vx install node@18.17.0 --force


# Clear cache and retry

vx cleanup --cache-only

vx install node@18.17.0


# Use system Node.js as fallback

vx --use-system-path node --version

Performance

Fast Downloads: Parallel downloading with progress tracking
Efficient Storage: Shared installations across virtual environments
Quick Execution: Minimal overhead for tool execution
Smart Caching: Version metadata and download caching

Security

Checksum Verification: SHA256 verification of downloads
HTTPS Only: Secure downloads from official sources
Signature Validation: GPG signature verification (when available)
Sandboxed Execution: Isolated execution environments

Troubleshooting

Installation Issues

# Check available versions

vx search node


# Verify network connectivity

curl -I https://nodejs.org/dist/


# Check disk space

vx stats


# Force reinstall

vx remove node@18.17.0

vx install node@18.17.0

Runtime Issues

# Check Node.js installation

vx node --version

vx npm --version


# Verify PATH configuration

vx which node

vx which npm


# Test with system Node.js

vx --use-system-path node --version

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

Related Crates

vx-core - Core functionality
vx-cli - Command-line interface
vx-pm-npm - NPM package manager
vx-tool-uv - UV Python tool

vx-tool-node 0.2.3