πŸ“¦ NPX (Node Package eXecute) on Debian Cheat Sheet

πŸ“¦ NPX (Node Package eXecute) on Debian Cheat Sheet #

Complete guide for using NPX package runner on Debian systems with best practices and security considerations.

πŸ“‹ Table of Contents #

  1. What is NPX
  2. NPX vs NPM
  3. Installation on Debian
  4. Basic Usage
  5. Command Options
  6. Common Use Cases
  7. Security Best Practices
  8. Advanced Features
  9. Troubleshooting
  10. Performance Tips

🎯 What is NPX #

NPX (Node Package eXecute) is a package runner tool that comes bundled with npm 5.2+ and allows you to execute npm packages without installing them globally.

Key Features #

  • Execute without installation: Run packages directly from npm registry
  • Temporary execution: Downloads packages to temporary cache, removes after use
  • Version flexibility: Always uses latest version unless specified
  • Local binary priority: Checks local node_modules/.bin first
  • GitHub execution: Can run packages directly from GitHub repositories

How NPX Works #

# NPX execution flow:
# 1. Check if command exists in $PATH
# 2. Check local node_modules/.bin
# 3. If not found, download from npm registry
# 4. Execute the package
# 5. Clean up temporary files

βš–οΈ NPX vs NPM #

NPM (Node Package Manager) #

# Traditional approach - install then use
npm install -g create-react-app
create-react-app my-app

# Or install locally
npm install create-react-app
./node_modules/.bin/create-react-app my-app

NPX (Node Package eXecute) #

# Direct execution - no installation needed
npx create-react-app my-app

# Always uses latest version
npx cowsay "Hello World"

Comparison Table #

Feature NPM NPX
Installation Required Optional
Global pollution Yes No
Version control Manual updates Always latest
Disk space Permanent Temporary
Execution speed Faster (cached) Slower (download)

🐧 Installation on Debian #

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# Install Node.js and npm (includes npx)
sudo apt update
sudo apt install -y nodejs

# Verify installation
node --version
npm --version
npx --version

Method 2: Debian Default Repository #

# Install from Debian repos (may be older version)
sudo apt update
sudo apt install -y nodejs npm

# Verify installation
node --version
npm --version

Method 3: Using Node Version Manager (NVM) #

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install latest LTS Node.js
nvm install --lts
nvm use --lts

# NPX comes bundled
npx --version

Method 4: Using UV Package Manager #

# Install uv first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Node.js via uv
uv tool install nodejs

# Verify installation
node --version
npx --version

πŸš€ Basic Usage #

Simple Package Execution #

# Run a package without installing
npx cowsay "Hello Debian!"

# Create React app
npx create-react-app my-react-app

# Start HTTP server in current directory
npx http-server

# Run TypeScript compiler
npx tsc --init

# Execute Prettier formatter
npx prettier --write .

Version-Specific Execution #

# Use specific version
npx create-react-app@4.0.0 my-app

# Use version range
npx typescript@~4.5.0 tsc --version

# Use beta/alpha versions
npx create-next-app@beta my-next-app

Local vs Remote Execution #

# Force use local version (if exists)
npx --no-install prettier --version

# Force download fresh version
npx --ignore-existing create-react-app my-app

# Check what would be executed
npx --dry-run create-react-app my-app

βš™οΈ Command Options #

Core Options #

# Package specification
npx -p <package> <command>          # Specify package explicitly
npx -p lodash -p axios node script.js  # Multiple packages

# Installation control
npx --no-install <command>          # Only use if already installed
npx --ignore-existing <command>     # Always download fresh

# Output control
npx --quiet <command>               # Suppress npx output
npx --verbose <command>             # Show detailed output

# Shell and environment
npx -c "echo $npm_package_name"     # Execute shell command
npx --shell=bash <command>          # Specify shell

# Node.js options
npx --node-arg="--inspect" <command>  # Pass args to node
npx --node-arg="--max-old-space-size=4096" <command>

Advanced Options #

# Cache management
npx --cache /tmp/custom-cache <command>

# User configuration
npx --userconfig ~/.custom-npmrc <command>

# Version and help
npx --version                       # Show npx version
npx --help                         # Show help information

πŸ’‘ Common Use Cases #

Development Tools #

# Scaffolding and generators
npx create-react-app my-app
npx create-next-app my-next-app
npx create-vue@latest my-vue-app
npx @angular/cli new my-angular-app
npx create-svelte my-svelte-app

# Build tools and bundlers
npx webpack --mode production
npx rollup -c
npx vite build
npx parcel build src/index.html

# Testing frameworks
npx jest --init
npx playwright install
npx cypress open
npx vitest run

Code Quality Tools #

# Linting and formatting
npx eslint src/
npx prettier --write .
npx stylelint "**/*.css"
npx markdownlint "**/*.md"

# Type checking
npx tsc --noEmit
npx flow check

# Security auditing
npx audit-ci
npx snyk test
npx npm-check-updates

Utility Tools #

# HTTP servers
npx http-server -p 8080
npx serve build/
npx live-server

# File operations
npx rimraf node_modules
npx mkdirp deep/nested/path
npx cpx "src/**/*.js" dist/

# Package management
npx npm-check-updates -u
npx depcheck
npx license-checker

GitHub and Git Tools #

# Run from GitHub directly
npx github:user/repo
npx github:sindresorhus/trash-cli file.txt

# Git utilities
npx husky install
npx lint-staged
npx commitizen
npx semantic-release

πŸ”’ Security Best Practices #

Package Verification #

# Always verify package names to avoid typosquatting
# Correct: create-react-app
# Malicious: create-react-ap, creat-react-app

# Check package info before running
npm info create-react-app
npm view create-react-app repository

# Use specific versions for production
npx create-react-app@5.0.1 my-app

Execution Safety #

# Disable script execution for safety
npm config set ignore-scripts true

# Use --no-install to only run local packages
npx --no-install prettier --version

# Review package contents
npm pack create-react-app --dry-run

Environment Security #

# Use dedicated user for npm operations
sudo adduser --system --group npmuser
sudo -u npmuser npx create-react-app my-app

# Limit network access (using firejail)
firejail --net=none npx local-package

# Use container isolation
docker run --rm -v $(pwd):/app -w /app node:18 npx create-react-app my-app

Audit and Monitoring #

# Regular security audits
npx audit-ci --moderate
npx better-npm-audit audit

# Check for known vulnerabilities
npx snyk test
npx safety-cli scan

# Monitor package changes
npx npm-check-updates --doctor

πŸ”§ Advanced Features #

Shell Auto-Fallback #

# Enable shell fallback for bash
npx --shell-auto-fallback bash >> ~/.bashrc
source ~/.bashrc

# Enable for zsh
npx --shell-auto-fallback zsh >> ~/.zshrc
source ~/.zshrc

# Now unknown commands automatically try npx
unknown-command --help  # Tries: npx unknown-command --help

Custom Package Execution #

# Execute specific binary from package
npx -p @angular/cli ng new my-app
npx -p typescript tsc --version

# Multiple packages in single command
npx -p cowsay -p lolcatjs -c 'cowsay hello | lolcatjs'

# Execute with custom environment
NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx create-react-app my-app

Scripting with NPX #

#!/bin/bash
# Script to create and setup React app

APP_NAME=$1
if [ -z "$APP_NAME" ]; then
    echo "Usage: $0 <app-name>"
    exit 1
fi

# Create app
npx create-react-app "$APP_NAME"
cd "$APP_NAME"

# Add additional dependencies
npx -p npm-check-updates ncu -u
npm install

# Setup linting
npx eslint --init

echo "App $APP_NAME created and configured!"

Integration with CI/CD #

# GitHub Actions example
- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18'

- name: Run tests with npx
  run: |
    npx jest --ci --coverage
    npx codecov

# GitLab CI example
test:
  script:
    - npx jest --ci
    - npx eslint src/

🚨 Troubleshooting #

Common Issues and Solutions #

NPX Command Not Found #

# Check if npm is installed
npm --version

# Reinstall npm
sudo apt remove nodejs npm
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Check PATH
echo $PATH | grep -o '/usr/local/bin\|/usr/bin'

Permission Errors #

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Alternative: use npx with sudo (not recommended)
sudo npx create-react-app my-app
sudo chown -R $USER:$USER my-app

Network and Proxy Issues #

# Configure proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Use different registry
npm config set registry https://registry.npmjs.org/

# Clear npm cache
npm cache clean --force

Package Not Found #

# Check package name
npm search create-react-app

# Try with explicit package flag
npx -p create-react-app create-react-app my-app

# Check npm registry status
curl -I https://registry.npmjs.org/

Version Conflicts #

# Clear npx cache
rm -rf ~/.npm/_npx

# Force fresh download
npx --ignore-existing create-react-app my-app

# Use specific version
npx create-react-app@latest my-app

Debugging Commands #

# Verbose output
npx --verbose create-react-app my-app

# Dry run (see what would happen)
npx --dry-run create-react-app my-app

# Check npx configuration
npm config list
npm config get cache
npm config get prefix

# Check installed packages
npm list -g --depth=0

⚑ Performance Tips #

Caching Strategies #

# Pre-download frequently used packages
npx create-react-app --help  # Downloads and caches

# Use local installations for repeated use
npm install -g create-react-app  # Then use directly
create-react-app my-app

# Custom cache location
export NPM_CONFIG_CACHE=/tmp/npm-cache
npx create-react-app my-app

Network Optimization #

# Use faster registry mirrors
npm config set registry https://registry.npm.taobao.org/

# Enable offline mode (use cached packages only)
npm config set offline true
npx --no-install create-react-app my-app

# Parallel downloads
npm config set maxsockets 20

Resource Management #

# Limit memory usage
npx --node-arg="--max-old-space-size=2048" webpack

# Clean up after use
rm -rf ~/.npm/_npx  # Clear npx cache
npm cache clean --force  # Clear npm cache

# Monitor resource usage
htop  # While running npx commands

πŸ“š Useful Commands Reference #

Quick Operations #

# One-liner React app with TypeScript
npx create-react-app my-app --template typescript

# Quick HTTP server with CORS
npx http-server -p 3000 --cors

# Instant code formatting
npx prettier --write "**/*.{js,jsx,ts,tsx,json,css,md}"

# Quick package info
npx npm-check-updates --doctor

# Generate package.json
npx npm init -y

Development Workflow #

# Start new project workflow
npx create-react-app my-project
cd my-project
npx husky install
npx lint-staged --init
npx prettier --write .
npm start

Maintenance Commands #

# Update all dependencies
npx npm-check-updates -u && npm install

# Security audit
npx audit-ci --moderate

# Clean project
npx rimraf node_modules package-lock.json
npm install

# Check bundle size
npx bundlesize

🎯 Best Practices Summary #

  1. Always verify package names to avoid typosquatting attacks
  2. Use specific versions for production deployments
  3. Enable security auditing with tools like audit-ci
  4. Prefer local installations for frequently used packages
  5. Use --no-install flag when you want to use only local packages
  6. Keep npm and Node.js updated for latest security patches
  7. Use shell auto-fallback for better developer experience
  8. Monitor package dependencies regularly
  9. Use containers or sandboxing for untrusted packages
  10. Clear caches regularly to free up disk space

Scaffolding Tools #

  • create-react-app - React application generator
  • create-next-app - Next.js application generator
  • @angular/cli - Angular CLI
  • create-vue - Vue.js project generator
  • create-svelte - Svelte application generator

Development Tools #

  • http-server - Simple HTTP server
  • live-server - Development server with live reload
  • json-server - Mock REST API server
  • serve - Static file serving
  • nodemon - File watcher for Node.js

Code Quality #

  • eslint - JavaScript linter
  • prettier - Code formatter
  • stylelint - CSS linter
  • markdownlint - Markdown linter
  • audit-ci - Security audit tool

This cheat sheet covers comprehensive NPX usage on Debian systems. Always verify packages before execution and follow security best practices.