vx-tool-node 0.2.5

Node.js tool support for vx
Documentation

vx-tool-node

Crates.io Documentation License: MIT

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

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

Installation Process

  1. Version Lookup: Query Node.js release API
  2. Download: Fetch appropriate binary/installer
  3. Extraction: Extract to vx tools directory
  4. Verification: Verify installation integrity
  5. 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