@gjuoun/ripgrep

npm binary distribution of ripgrep — install rg as an npm dependency, no system install, no postinstall, no runtime download. Modeled after @vscode/ripgrep (and its siblings, @gjuoun/fd and @gjuoun/ast-grep).

Use it when your tool, CLI, or agent needs ripgrep (extremely fast, gitignore-aware recursive text search) on any machine where it is not installed — lean clients, containers, CI, remote hosts. npm install is the only setup step.

Note: jun-agent already depends on @vscode/ripgrep for the same purpose. This package exists for series consistency and provenance ownership under the gjuoun npm scope alongside @gjuoun/fd/@gjuoun/ast-grep — not because @vscode/ripgrep is broken or insufficient.

Install

npm install @gjuoun/ripgrep
# or
bun add @gjuoun/ripgrep

npm automatically installs exactly one platform package matching your os/cpu (via optionalDependencies); nothing is downloaded at runtime.

Usage

Get the binary path

import { rgPath } from "@gjuoun/ripgrep";

console.log(rgPath);
// → /path/to/node_modules/@gjuoun/ripgrep-darwin-arm64/bin/rg

Run ripgrep from your code

import { spawnSync } from "node:child_process";
import { rgPath } from "@gjuoun/ripgrep";

const result = spawnSync(rgPath, ["--json", "TODO"], { encoding: "utf8" });
console.log(result.stdout); // matching lines, as ripgrep's --json event stream

CommonJS works too

const { rgPath } = require("@gjuoun/ripgrep");

API

export const rgPath: string;

| Export | Type | Description | |---|---|---| | rgPath | string | Absolute path to the rg binary for the current platform (via require.resolve against the matching platform package). |

Throws Error at import time if no platform package matches the current process.platform / process.arch — the message names the expected package and the npm install -O <pkg> fix.

Platform packages

| Package | os | cpu | libc | |---|---|---|---| | @gjuoun/ripgrep-darwin-arm64 | darwin | arm64 | — | | @gjuoun/ripgrep-darwin-x64 | darwin | x64 | — | | @gjuoun/ripgrep-linux-x64 | linux | x64 | glibc, musl | | @gjuoun/ripgrep-linux-arm64 | linux | arm64 | glibc |

No Windows packages: scoped out, mirroring @gjuoun/fd's and @gjuoun/ast-grep's Unix-only footprint (upstream does publish *-pc-windows-msvc/*-pc-windows-gnu assets — add packages for them if Windows support is ever needed).

The linux-x64 / linux-arm64 libc asymmetry

Upstream ripgrep 15.2.0 publishes no x86_64-unknown-linux-gnu asset — musl is the only x64 Linux build (verified live via gh release view 15.2.0 --repo BurntSushi/ripgrep). That musl build is static-pie linked (confirmed with file: no dynamic interpreter, no runtime libc dependency), so it runs on both glibc and musl x64 hosts. @gjuoun/ripgrep-linux-x64's package.json therefore declares "libc": ["glibc", "musl"] — not musl-only — so npm doesn't skip installing it on ordinary glibc distros (Ubuntu, Debian, etc.), which would otherwise leave the majority of Linux x64 users with no working package at all.

linux-arm64 uses the aarch64-unknown-linux-gnu asset instead (dynamically linked against glibc, confirmed via file: interpreter /lib/ld-linux-aarch64.so.1). Upstream also publishes an aarch64-unknown-linux-musl asset, but this distribution tracks only one Linux arm64 package — matching the gnu choice @gjuoun/ast-grep and @gjuoun/fd already made for their own linux-arm64 packages — so it will not run on musl (Alpine) arm64 hosts.

Development

Binaries are not committed. Rebuild them from the pinned upstream release, then test:

bun scripts/fetch.ts   # download + verify against upstream .sha256 sidecars + unpack
bun test               # unit + resolver tests
bun scripts/pack-check.ts

ripgrep publishes a per-asset .sha256 sidecar file for every release asset (standard sha256sum output, e.g. ripgrep-15.2.0-x86_64-apple-darwin.tar.gz.sha256), so fetch.ts downloads and verifies against that sidecar directly — no GitHub API digest fallback needed here (unlike @gjuoun/ast-grep, which had no sidecar files upstream).

License

MIT © Jun Guo