Noxedo

A tiny nox-style session runner for JavaScript and TypeScript projects.

You define sessions in a small JS/TS module (a "noxfile") and noxedo runs each one in its own isolated environment. The isolated environment is a clean copy of your project with only its production dependencies installed, plus whatever extra packages the session declares (test tooling, optional peers, alternate versions).

Usage

Write a noxedo.config.mjs (or .js) at your project root:

import { session } from "noxedo";

// Test tooling is typically a dev dependency, so a session declares it explicitly.
session("core", { description: "no optional deps" }, (s) => {
  s.install("vitest");
  s.run("pnpm test");
});

// Optional packages/peers like `myPeer` are declared the same way.
session("full", { description: "with the optional myPeer peer present" }, (s) => {
  s.install("vitest", "myPeer");
  s.run("pnpm test");
});

Then:

noxedo            # run every session
noxedo core       # run only the named session(s)
noxedo --list     # list sessions without running

The package manager is detected from your lockfile (pnpm-lock.yaml, package-lock.json, or yarn.lock), so the same pnpm test you run locally is what runs in the env. Sessions run in registration order, the runner continues past failures, prints a pass/FAIL summary, and exits non-zero if any session failed.

The session context

| Method | Description | | --- | --- | | s.install(...specs) | Install extra packages on top of the project's base install ("somePeer", "[email protected]", ...). The project itself is already present. | | s.run(command) | Run a shell command in the env; a non-zero exit fails the session. Call it repeatedly to sequence steps. | | s.env(vars) | Merge environment variables applied to subsequent install/run calls. | | s.dir | Absolute path to this session's env directory. |

CLI

| Option | Default | Description | | --- | --- | --- | | names... | all | sessions to run | | -c, --config <path> | noxedo.config.mjs or .js | noxfile to load | | -l, --list | | list sessions without running | | -h, --help | | show help |

Each session is provisioned under the system temp dir.

Library

The runner is also importable, with the IO (command execution, filesystem, copy) injectable so it can be driven in tests:

import { runSessions, selectSessions, sessions, defaultRunDeps } from "noxedo";

const selected = selectSessions(sessions(), ["core"]);
const results = await runSessions(selected, defaultRunDeps());

Development

pnpm install
pnpm test
pnpm run start -- --list