hni 0.0.3

ni-compatible package manager command router with node shim
Documentation

hni

hni og banner

CI License: GPLv3 crates.io npm npm yarn pnpm bun deno

Fast package manager routing for npm, yarn, pnpm, bun, and deno.

hni is inspired by Antfu's ni, but packaged as a single multicall binary with extra shell setup for a node shim.

hni is still beta software and may have bugs.

One install gives you:

  • hni
  • ni, nr, nlx, nru, nun, nci, na, np, ns
  • node shim via hni init <shell> (shell plugin only)

Install

npm (global)

npm install -g @happytoolin/hni
hni --version

This installs hni and the ni-family aliases (ni, nr, nlx, nru, nun, nci, na, np, ns) onto your global npm bin path. The node shim is only enabled through hni init <shell>. Under the hood, npm resolves a platform-specific optional dependency package that contains the native hni binary.

Homebrew

brew tap happytoolin/happytap
brew install hni
hni --version

Script install (macOS / Linux)

TODO: https://happytoolin.com/hni/install.sh is not live yet. Use the raw GitHub script for now:

curl -fsSL https://raw.githubusercontent.com/happytoolin/hni/main/install.sh | bash

Optional environment variables:

  • HNI_VERSION - install a specific version, for example v0.0.2
  • HNI_INSTALL_DIR - install somewhere other than ~/.local/bin
  • HNI_NODE=off - disable the node shim for the current environment

Script install (PowerShell)

TODO: https://happytoolin.com/hni/install.ps1 is not live yet. Use the raw GitHub script for now:

irm https://raw.githubusercontent.com/happytoolin/hni/main/install.ps1 | iex

Optional parameters:

  • -Version latest
  • -InstallDir "$env:LOCALAPPDATA\hni\bin"

Deno / JSR

Install hni:

deno install -gA -n hni jsr:@happytoolin/hni/hni
hni --version

Install alias commands (example):

deno install -gA -n ni jsr:@happytoolin/hni/ni
deno install -gA -n nr jsr:@happytoolin/hni/nr

Commands

ni

Install dependencies or add new ones.

ni
ni vite
ni -D vitest
ni -g eslint
ni --frozen
ni --frozen-if-present
ni --interactive

nr

Run package scripts.

nr
nr dev
nr build
nr test -- --watch
nr --if-present lint

nlx

Execute binaries without adding them permanently to your project.

nlx vitest
nlx eslint .
nlx create-vite@latest

nru

Upgrade dependencies. Named nru to avoid shadowing Nushell's nu binary.

nru
nru react react-dom
nru --interactive

nun

Remove dependencies.

nun lodash
nun react react-dom
nun --multi-select
nun -g typescript

nci

Run a clean install. If a lockfile exists, hni uses the package-manager-specific frozen install command.

nci

na

Print or forward directly to the detected package manager.

na --version
na config get registry

np / ns

Run shell commands in parallel or sequentially.

np "pnpm dev" "pnpm test"
ns "pnpm lint" "pnpm test"

node

hni can also act as a package-manager-aware node shim. Enable it by adding hni init <shell> to your shell config first.

node install vite
node run dev
node exec vitest
node ci
node p "echo one" "echo two"

Regular Node.js usage still passes through:

node script.js
node -v
node -- --trace-warnings

Utilities

hni help ni
hni completion zsh
hni init bash
hni doctor

Shell Setup

If you want node-shim behavior, add the init line at the end of your shell config file, after anything that manages Node or rewrites PATH, such as nvm, mise, asdf, fnm, or volta.

Do not append the hni directory to the end of PATH. Put the init line at the end of the shell config file and let it prepend the correct path for you.

zsh

Add to ~/.zshrc:

eval "$(hni init zsh)"

bash

Add to ~/.bashrc:

eval "$(hni init bash)"

fish

Add to ~/.config/fish/config.fish:

hni init fish | source

PowerShell

Add to $PROFILE:

Invoke-Expression (& hni init powershell)

Nushell

Generate a stable init file, then source it from the end of ~/.config/nushell/config.nu:

hni init nushell | save --force ~/.config/nushell/hni.nu
source ~/.config/nushell/hni.nu

Global Flags

These work across hni and the multicall aliases:

? --dry-run --print-command
--explain
-C <dir>
-v --version
-h --help

Use -- to forward flags to the underlying package manager or script:

hni ni -- --help
nr test -- --watch

Configuration

Config file:

  • ~/.hnirc

Supported keys:

defaultPackageManager=pnpm
globalPackageManager=npm
fastMode=true

Environment overrides:

  • HNI_CONFIG_FILE
  • HNI_DEFAULT_PACKAGE_MANAGER
  • HNI_GLOBAL_PACKAGE_MANAGER
  • HNI_FAST

How It Works

hni detects the package manager from:

  1. packageManager in package.json
  2. lockfiles such as pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock, package-lock.json, bun.lockb, or deno.lock
  3. devEngines.packageManager in package.json
  4. install metadata such as .pnp.cjs, node_modules/.pnpm, or node_modules/.package-lock.json
  5. config defaults if detection is unavailable

Then it maps the command family to the right underlying command:

  • ni -> install or add
  • nr -> run or task
  • nlx -> npx / pnpm dlx / yarn dlx / bun x
  • nru -> update / upgrade
  • nci -> frozen install when lockfiles exist

Troubleshooting

PowerShell ni alias conflict

PowerShell ships with a built-in ni alias for New-Item.

If that conflicts with hni, remove or override it in your profile before loading hni:

Remove-Item Alias:ni -ErrorAction SilentlyContinue
Invoke-Expression (& hni init powershell)

Check what hni resolved

ni vite --debug-resolved
nr dev --explain
hni doctor

Benchmarking

The active benchmark suite lives in benchmark/.

If you use just, the common local commands are wrapped in justfile:

just build-release
just test
just test-fast
just ci
just bench

Run the default local benchmark with:

./benchmark/run.sh
just bench

Pass options through either entrypoint:

./benchmark/run.sh --track=compare
./benchmark/run.sh --track=fast
./benchmark/run.sh --track=runtime
./benchmark/run.sh --track=direct
just bench --track=direct --runs=3 --warmups=1 --no-build

Run the full release-style matrix with:

./benchmark/run.sh --track=all --runs=500 --warmups=50

Generate flamegraphs with:

./benchmark/profile.sh

Tracked benchmark docs:

Representative Results

The tracked snapshot in benchmark/LATEST.md was generated from the direct track with 2 warmups and 10 measured runs per case.

If you only want the headline, it is this: hni --fast averaged 5.44x faster than direct package-manager commands in the latest direct run.

The fast track compares pm mode versus fast mode inside hni across npm, pnpm, yarn, bun, deno, and local-bin execution. In the latest local fast run, hni --fast averaged 4.57x faster than pm mode.

A few representative wins:

Case pm fast Relative
nr noop (npm) 214.19 ms 28.59 ms 7.49x
nr noop (pnpm) 427.88 ms 28.81 ms 14.85x
nr noop (yarn) 264.11 ms 28.85 ms 9.16x
node run noop (pnpm) 429.05 ms 29.00 ms 14.80x
node run noop (bun) 33.82 ms 29.00 ms 1.17x
nlx hello --flag (npm local bin) 250.63 ms 5.15 ms 48.71x

The direct track also compares normal package-manager usage (npm run, pnpm exec, yarn, bun x, deno task) with hni --fast. In the latest local direct run, hni averaged 5.44x faster, including local-bin wins for pnpm exec (52.40x) and yarn (16.98x).

Methodology

All timing uses hyperfine against the release binary. The suite can look at four angles:

  • direct: normal package-manager usage versus hni --fast
  • fast: pm mode versus fast mode inside hni
  • compare: a small CLI-focused comparison against Antfu's ni
  • runtime: a side-by-side look at hni, bun, and deno on a couple of task-style cases

The repo keeps the curated snapshot files rather than every intermediate result. For the current tracked result, use benchmark/LATEST.md.