# Use Node.js, npm, and pnpm with OMG

Separate runtime selection from dependency installation. Use an OMG-managed Node.js with npm or pnpm and let the OMG task runner execute project scripts across tools.

Canonical: https://getomg.xyz/guides/node-npm-pnpm/
Updated: 2026-09-22
Author: OMG maintainers

## 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

```sh
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

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

> OMG’s task runner selects npm, pnpm, Yarn, or Bun from package.json packageManager or recognized lockfiles. The published CLI recognizes bun.lockb, but not Bun’s newer bun.lock; set packageManager to bun in package.json for a bun.lock project. Deno tasks are read from deno.json.

## 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

```sh
omg run dev
omg run build
omg run test -- --watch
```

## Sources and verification

Source-reviewed guidance; not a claim of execution on every supported platform.

- [OMG runtime handbook](https://getomg.xyz/docs/runtimes/)

- [pnpm installation](https://pnpm.io/installation)

- [OMG polyglot task runner (src/core/task_runner.rs)](https://getomg.xyz/guides/task-runner/)

- [npm ci command documentation](https://docs.npmjs.com/cli/commands/npm-ci)

- [Bun lockfile documentation](https://github.com/oven-sh/bun/blob/main/docs/pm/lockfile.mdx)

## Related pages

- https://getomg.xyz/runtimes/node/

- https://getomg.xyz/guides/migrate-from-nvm/

- https://getomg.xyz/compare/omg-vs-mise/