vscode-ripgrep

@vscode/ripgrep is the npm wrapper Visual Studio Code itself uses to bundle the ripgrep search binary into Node projects. Instead of compiling ripgrep from source or shelling out to a system install, the package resolves a per-platform binary package (@vscode/ripgrep-<os>-<cpu>) installed transitively via optionalDependencies, and exposes its path as rgPath at runtime.

Because every binary ships as a signed, prebuilt npm package rather than being downloaded on install, there is no postinstall script and no runtime network access — the tarball for the current platform is simply present after npm install. A companion @vscode/ripgrep-universal package bundles every platform’s binary into one install for cross-platform repackaging use cases.

What You Get

• A pure-JS rgPath export that resolves to the correct native ripgrep binary for the current OS/CPU at runtime, with no build step required
• Per-platform binary packages (@vscode/ripgrep-<os>-<cpu>) installed transitively via optionalDependencies, so consumers only download the binary they actually need
• A @vscode/ripgrep-universal package that bundles every supported platform’s binary in one install, plus a binPathFor({ os, arch }) helper for cross-compiling or repackaging tools
• Binaries verified against SHA256 hashes recorded in binaries.lock.json at build time, sourced from the microsoft/ripgrep-prebuilt release assets
• Coverage across 12 platform/arch targets including Windows, macOS (x64/arm64), and Linux (x64, arm64, arm, ppc64, riscv64, s390x, ia32)

Common Use Cases

• Powering fast in-editor text search, as VS Code itself does, without asking the user to install ripgrep separately
• Adding native, high-performance file-content search to a CLI tool or desktop app built on Node/Electron
• Bundling a single cross-platform artifact (via @vscode/ripgrep-universal) when packaging a tool for distribution across all supported OSes from one build host
• Replacing a shelled-out call to a system grep/rg binary with a guaranteed-present, version-pinned dependency

Under The Hood

Architecture The repository is an npm workspaces monorepo rooted at a private vscode-ripgrep-monorepo package, with packages/ripgrep as the published entry point and one packages/ripgrep-<os>-<cpu> directory per supported platform target plus packages/ripgrep-universal. packages/ripgrep/lib/index.js does the only real work at runtime: it builds a platform package name (@vscode/ripgrep-${process.platform}-${arch}) and uses require.resolve (via createRequire in an ESM module) to locate that platform package’s bin/rg binary, throwing a clear error if the optional dependency wasn’t installed for the current platform. build/platforms.js is the single source of truth for the platform/target/version matrix, consumed by both build/prepare-binaries.js (downloads and SHA256-verifies each platform’s ripgrep archive from microsoft/ripgrep-prebuilt into packages/ripgrep-<os>-<cpu>/bin/) and build/sync-packages.js (materializes each platform package’s package.json, README, and LICENSE, and keeps the wrapper’s optionalDependencies versions in sync with the root version). Nothing in this data flow touches the network at install time — verification and download both happen at publish time, driven by an Azure Pipelines template (build/pipeline.yml) that runs one job per platform package.

Tech Stack Plain Node.js with no runtime dependencies at all — the wrapper package’s only dependency is itself an optionalDependencies map pinning exact versions of the twelve platform packages. Build tooling is a handful of small CommonJS scripts (build/prepare-binaries.js, build/sync-packages.js) using only Node built-ins (fs, path, https, crypto, child_process) — no bundler, no transpiler. The published wrapper and universal packages are authored as native ESM ("type": "module") with a hand-written .d.ts for types, while the build scripts themselves stay CommonJS. CI/publishing runs on Azure Pipelines via a shared microsoft/vscode-engineering template, not GitHub Actions.

Code Quality No automated test suite exists in the repository — correctness for each release instead rests on the SHA256 verification step in prepare-binaries.js, which fails the build outright on a hash mismatch against binaries.lock.json, and on JSDoc @ts-check annotations across the build scripts that give some static-typing safety without a full TypeScript build. Error handling in the runtime path is minimal but explicit: lib/index.js wraps its require.resolve call in a try/catch and throws a descriptive error naming the missing platform package rather than failing silently. Naming is consistent throughout (platformPkg, binaryName, packageNameFor), and the monorepo’s package boundaries are enforced structurally rather than by convention.

What Makes It Unique Rather than downloading or compiling a native binary on npm install — the common pattern for wrapping a Rust/Go CLI tool in npm, and one that depends on network access and a working toolchain at install time — this package pushes that cost entirely to publish time and lets npm’s own optionalDependencies platform-resolution mechanism do the selection work. That trade produces installs that are fully offline-capable and deterministic, at the cost of publishing thirteen separate npm packages (one wrapper, eleven per-platform binaries, one universal bundle) per ripgrep version bump — a trade this specific project can absorb because VS Code’s own release cadence already needs that level of automation.