binpx

Language: English(now) | 简体中文

Run locally installed npm binaries - a lightweight alternative to npx

Features

• Lightweight - No registry queries, no unnecessary dependencies, only local lookup
• Multi-format - Supports CJS, ESM, and CLI
• Smart lookup - Finds binaries in current and parent directories
• Cross-platform - Works on Windows, Linux, and macOS
• Multi-package manager - Supports npm, pnpm, yarn, and more
• Flexible API - Promise-based with raw mode option
• Fast - Up to 8x faster than npx

Install

npm install binpx

Usage

CLI (Command Line)

# Run locally installed eslint
binpx eslint --fix

# Run locally installed jest
binpx jest --coverage

# Run locally installed TypeScript compiler
binpx tsc --noEmit

# Show help
binpx --help
binpx -h

# Show version
binpx --version
binpx -v

ES Module (import)

import binpx from 'binpx'

// Basic usage
await binpx('eslint', ['--fix'])

// Collect output
const { stdout, stderr } = await binpx('eslint', ['--format', 'json'], {
    collectOutput: true
})
console.log(stdout)

// Real-time output (raw mode)
const proc = await binpx('npm', ['run', 'dev'], { raw: true })
proc.stdout.on('data', (data) => console.log(data.toString()))

// Disable fallback to system command
await binpx('custom-tool', [], { allowFallback: false })

// Custom working directory
await binpx('jest', ['--coverage'], { cwd: './packages/core' })

CommonJS (require)

const binpx = require('binpx')

// Basic usage
await binpx('eslint', ['--fix'])

// Collect output
const { stdout } = await binpx('prettier', ['--check', 'src/'], {
    collectOutput: true
})

// Real-time output
const proc = await binpx('npm', ['run', 'build'], { raw: true })
proc.stdout.on('data', (chunk) => process.stdout.write(chunk))

// With options
await binpx('jest', ['--coverage'], { 
    cwd: './src',
    allowFallback: false 
})

API

binpx(commandName, argv, options)

| Parameter | Type | Description | |-----------|------|-------------| | commandName | string | Command name (e.g., 'eslint', 'jest') | | argv | string[] | Arguments array (e.g., ['--fix']) | | options | object | Configuration options |

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | cwd | string | process.cwd() | Working directory | | allowFallback | boolean | true | Fallback to system command if not found locally | | collectOutput | boolean | true | Collect stdout/stderr (returns {stdout, stderr, code}) | | raw | boolean | false | Return ChildProcess directly for real-time handling | | isShell | boolean | true | Whether to use shell for execution (On Windows environment, false may cause command failure) | | Others | any | / | Passed through to spawn options |

Return Values

| Mode | Return Type | Description | |------|-------------|-------------| | Default | Promise<{code}> | Resolves when command completes | | collectOutput: true | Promise<{stdout, stderr, code}> | Returns captured output | | raw: true | ChildProcess | Returns spawn object directly |

How It Works

1. Searches upward from cwd for node_modules/.bin/{command}
2. If found, executes the local binary
3. If not found and allowFallback is true, falls back to system command
4. Otherwise throws an error

Why binpx?

| Feature | npx | binpx | |---------|-----|-------| | Local binary lookup | ✅ | ✅ | | Parent directory lookup | ✅ | ✅ | | Registry query | ✅ | ❌ | | Network required | ✅ | ❌ | | Installation required | ❌ | ✅ | | Supports other package managers | ❌ | ✅ | | Startup speed | Slow | Fast |

binpx is ideal for:

• CI/CD pipelines (no network needed)
• npm scripts (faster than npx)
• Projects where you want to ensure local binaries are used
• Offline environments

License

MIT