package-execution

JavaScript package execution

ipx runs package bins from the nearest installed node_modules; npx is an alias with the same behavior. If no local bin or installed package resolves, it normally installs the requested package and runs its bin.

Before that network install, mapped package names that duplicate SLICC built-ins redirect to the built-in instead. The command exits non-zero and prints an actionable stderr hint naming the built-in and suggesting an invocation with the original arguments. The hint may also include an exact ipk add bootstrap; run that bootstrap first when present, then use the suggested built-in.

Prefer the built-in. To deliberately preserve install-and-run behavior for the npm package, put --force before its name:

npx --force <package> [args...]
ipx --force <package> [args...]

Already-installed packages, locally resolved bins, and unmapped package names keep their normal behavior. Use commands to discover available built-ins instead of maintaining a package mapping here.

Installing and removing packages

ipk install <pkg> (also npm install, npm i, ipk add) installs into <cwd>/node_modules and records the package in the nearest package.json — in the section it already occupies, or in dependencies if it is new. ipk install -D <pkg> / npm install --save-dev <pkg> records new packages in devDependencies. A bare name that is already declared is resolved against that existing range, not latest. Versions are picked as pnpm picks them: a range takes the latest dist-tag whenever latest satisfies it (* always takes latest), and deprecated versions are passed over unless nothing else fits. Unknown install flags fail instead of being ignored. ipk install with no package names installs declared dependencies, devDependencies and optionalDependencies without rewriting package.json. ipk install -g <pkg> installs into the shared global prefix at /shared/lib/node_modules, records direct dependencies in /shared/lib/package.json, and publishes PATH-visible .jsh delegators under /shared/bin for package bins. Every downloaded tarball is checked against the registry's published hash before it is extracted. An EINTEGRITY error means that package's bytes did not match and it was not extracted, but packages installed before it may already be on disk and package.json was not updated. Check the state with ipk list, then retry the install; don't work around it. Installed files keep the package's executable bits (as npm sets them: 0755 for anything the tarball marks executable, 0644 otherwise), and bin targets are always executable, so a package's scripts and helpers (e.g. git submodule from @ai-ecoverse/wasm-git) run without chmod +x. A tree installed before this is repaired the next time you install into it. Platform-specific optional dependencies are skipped unless they are built for wasm (cpu: wasm32); the skipping optional dependency … (unsupported platform) notes are expected, not errors. For a napi-rs package that doesn't list its wasm binding, add <pkg>-wasm32-wasi (e.g. @oxc-parser/binding-wasm32-wasi) yourself.