nix-run

A Node.js library and CLI tool to run Nix packages and expressions easily.
Provides a full programmatic interface to the Nix package manager, allowing JavaScript/TypeScript applications to run packages, evaluate expressions, query nixpkgs, and work with Nix flakes.

✨ Features

• Run Nix Packages – Execute binaries from nixpkgs or custom flakes.
• Version Pinning – Select specific versions like nodejs:20.
• Expression Evaluation – Evaluate Nix expressions (JSON or raw).
• Package Search – Search nixpkgs programmatically.
• Flake Support – List apps, read metadata, run flake apps.
• Caching Layer – Cache store paths + metadata.
• CLI Tool – Use nix-run directly from the terminal.
• TypeScript – Fully typed APIs.

📦 Installation

Requirements

• Node.js 18+
• Nix installed (https://nixos.org/download)

Install via npm

npm install nix-run

For development:

git clone https://github.com/Viswesh934/nix-run.git
cd nix-run
npm install
npm run build

🚀 Quick Start

Run a Nix package (programmatically)

import { nixRun } from "nix-run";

const result = await nixRun("hello", [], { stream: false });
console.log(result.stdout); // → "Hello, world!"

CLI Usage

# Run a package
npx nix-run hello

# With arguments
npx nix-run ripgrep -- --help

📘 API Reference

nixRun(pkg, args, options)

Runs a nix package and returns { stdout, stderr, code }.

await nixRun("hello");
await nixRun("ripgrep", ["--version"]);
await nixRun("nodejs:20", ["--version"]);

NixExpression

Evaluate inline or file-based Nix expressions.

const expr = new NixExpression();
const result = await expr.eval("1 + 1");   // "2"
const json = await expr.evalJSON('{ a = 10; }');
// → { a: 10 }

NixQuery

Search and resolve nixpkgs.

const query = new NixQuery();
const results = await query.search("ripgrep");
const storePath = await query.resolveStorePath("coreutils");

NixFlake

Work with Nix flakes.

const flake = new NixFlake();

const meta = await flake.show("github:NixOS/nixpkgs");
const apps = await flake.listApps(".");
const run = await flake.runApp(".", "myapp");

🖥 CLI Usage

# Run packages
nix-run hello
nix-run nodejs -- --version
nix-run ripgrep -- --help

# With version pinning
nix-run nodejs:20 -- --version

📁 Project Structure

nix-run/
│
├── src/
│   ├── index.ts
│   ├── nixRun.ts
│   ├── nixVersion.ts
│   ├── nixUtils.ts
│   ├── nixExpression.ts
│   ├── nixDetect.ts
│   ├── nixQuery.ts
│   ├── nixFlake.ts
│   ├── nixShell.ts
│   ├── nixCache.ts
│   ├── utils/
│   │   ├── exec.ts
│   │   ├── logger.ts
│   │   └── env.ts
│   └── cli.ts
│
├── bin/          # CLI entrypoint
├── examples/
├── test/
├── docs/
└── .nix-runner/  # Cache directory

🧪 Testing

npm test

Tests requiring Nix are skipped automatically if Nix is not installed.

🤝 Contributing

Feel free to open issues or PRs.

📄 License

MIT — see LICENSE.

🔗 Related

• Nix Package Manager – https://nixos.org
• Nix Flakes – https://nixos.wiki/wiki/Flakes