Use Node.js, npm, and pnpm with OMG

Toolchain responsibilities and boundaries

Maintaining clean developer environments requires clear boundaries between runtime orchestration and project dependency management. Mixing these responsibilities leads to lockfile corruption and unexpected executable resolution.

Layer responsibilities in the Node.js ecosystem

Layer	Responsibility
OMG	Downloads, validates, and activates the Node.js runtime and its bundled npm/npx executables on PATH. Auto-switches versions based on project pins (.node-version, .nvmrc, package.json).
npm	Resolves JavaScript/TypeScript dependencies, creates node_modules, and maintains package-lock.json for npm-based repositories.
pnpm	Manages content-addressable dependencies, hard links, and maintains pnpm-lock.yaml for pnpm-based repositories.
OMG Task Runner	Auto-discovers and runs tasks declared in package.json (omg run <task>) across ecosystems with priority 90, passing arbitrary arguments directly.

Working with an existing npm project

When entering an npm project, OMG’s shell hook activates the Node.js version pinned in `.node-version` or `.nvmrc`. To ensure repeatable builds from your committed `package-lock.json`, use `npm ci` rather than `npm install`.

Verify environment and install with npm ci

omg which node
node --version
npm --version
npm ci
omg run test

Working with an existing pnpm project

pnpm uses its own global store and hard-link layout. When using OMG to provide the base Node.js interpreter for pnpm, ensure your frozen lockfile checks match the project requirements.

Verify environment and install with pnpm

node --version
pnpm --version
pnpm install --frozen-lockfile
omg run build

Cross-ecosystem task execution with OMG run

In `src/core/task_runner.rs`, OMG inspects `package.json` `scripts` and executes them directly. You do not need to remember whether a repository uses `npm run`, `pnpm run`, or `bun run`: `omg run` detects the appropriate runner automatically.

Execute project scripts through OMG

omg run dev
omg run build
omg run test -- --watch

Sources and verification

Commands and behavior are based on the references below. Source review is not a claim that every workflow has been executed on every supported platform.

Read as Markdown