{"id":17356,"library":"ripgrep","title":"ripgrep-node","description":"This `ripgrep` npm package provides the powerful command-line utility `ripgrep` in a fully cross-platform, dependency-free manner by compiling it to WebAssembly (WASM). As of version 0.3.1, it offers programmatic access to `ripgrep`'s core functionality, suitable for Node.js, Bun, Deno, and even bundler-friendly browser environments without requiring native binaries or post-install scripts. The package embeds the WASM module as a z85+brotli encoded string and leverages WASI for execution, defaulting to Node.js's built-in `node:wasi` for optimal performance when available. Its key differentiator is providing `ripgrep`'s capabilities entirely within the JavaScript ecosystem, making it a drop-in programmatic replacement for native `ripgrep` spawns, with the WASM module dynamically cached to the OS temp directory for subsequent fast access.","status":"active","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/pithings/ripgrep-node","tags":["javascript","typescript"],"install":[{"cmd":"npm install ripgrep","lang":"bash","label":"npm"},{"cmd":"yarn add ripgrep","lang":"bash","label":"yarn"},{"cmd":"pnpm add ripgrep","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is an ESM module. Use `import` for direct use or dynamic `import()` in CJS environments.","wrong":"const { ripgrep } = require('ripgrep');","symbol":"ripgrep","correct":"import { ripgrep } from 'ripgrep';"},{"note":"Provides the filesystem path to a JS shim that can be spawned as a child process, similar to `vscode-ripgrep`'s `rgPath`.","wrong":"const { rgPath } = require('ripgrep');","symbol":"rgPath","correct":"import { rgPath } from 'ripgrep';"}],"quickstart":{"code":"import { ripgrep, rgPath } from \"ripgrep\";\nimport { spawn } from \"node:child_process\";\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\n// Create a dummy file for searching\nconst tempDir = fs.mkdtempSync(path.join(process.cwd(), 'rg-temp-'));\nconst filePath = path.join(tempDir, 'test.txt');\nfs.writeFileSync(filePath, 'This is a test with TODO item one.\\nAnother line with TODO item two.');\n\nasync function runRipgrep() {\n  console.log('--- Running ripgrep programmatically (buffer output) ---');\n  try {\n    const { code, stdout, stderr } = await ripgrep([\"TODO\", tempDir], { buffer: true });\n    console.log(`Exit Code: ${code}`);\n    console.log(`STDOUT:\\n${stdout}`);\n    console.log(`STDERR:\\n${stderr}`);\n  } catch (e) {\n    console.error('Error running ripgrep programmatically:', e);\n  }\n\n  console.log('\\n--- Spawning ripgrep as a child process ---');\n  try {\n    const child = spawn(rgPath, [\"TODO\", tempDir], { stdio: \"pipe\" });\n    child.stdout.pipe(process.stdout);\n    child.stderr.pipe(process.stderr);\n    child.on('close', (code) => {\n      console.log(`Child process exited with code ${code}`);\n      fs.rmSync(tempDir, { recursive: true, force: true }); // Clean up\n    });\n  } catch (e) {\n    console.error('Error spawning ripgrep:', e);\n    fs.rmSync(tempDir, { recursive: true, force: true }); // Clean up\n  }\n}\n\nrunRipgrep();","lang":"typescript","description":"Demonstrates programmatic usage of `ripgrep` to search a temporary file, capturing its output, and an alternative method using `rgPath` with `node:child_process.spawn`."},"warnings":[{"fix":"Benchmark against native `ripgrep` for critical performance paths. Optimize search patterns or file sets as needed.","message":"Performance characteristics may differ from the native `ripgrep` binary, as this package runs `ripgrep` compiled to WebAssembly (WASM) via WASI. While optimized with SIMD, raw performance might vary depending on the workload and runtime environment.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Explicitly pass `--color=always` or `--color=ansi` in the `args` array to force colored output when using custom streams.","message":"When providing custom `stdout` or `stderr` streams, TTY auto-detection for `--color=ansi` is skipped. This can result in colorless output if not explicitly specified via `ripgrep` arguments.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure custom `stdout`/`stderr` streams passed in options have a valid `fd` property, or use `buffer: true` if streams are not strictly required.","message":"For streams used with `nodeWasi`, only streams with a numeric `fd` (file descriptor) property are supported. Custom streams without this property may cause unexpected behavior or errors.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure the runtime environment allows writing to the standard temporary directory. No direct configuration option is available to change the cache path.","message":"The WASM module is cached to the OS temp directory (`$TMPDIR/ripgrep-wasm-<hash>.wasm`) on first use. In environments with restricted temporary directory access or strict cleanup policies, this caching mechanism might be affected.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always explicitly provide the directory to search (e.g., `['pattern', './']`) or pass `stdio: ['ignore', 'pipe', 'pipe']` to `spawn` options to prevent `ripgrep` from waiting on stdin.","message":"Running `ripgrep` via `node:child_process.spawn` with `rgPath` and not explicitly managing stdin can cause `ripgrep` to hang in some versions, as `ripgrep` may default to searching stdin if no path is provided.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are running on a modern Node.js (16+ is recommended for `node:wasi`), Bun, Deno, or a browser with full WebAssembly/WASI support. Update your runtime or bundler configuration if targeting older environments.","cause":"The runtime environment (e.g., older Node.js, specific browser context) does not fully support modern WebAssembly APIs or WASI.","error":"TypeError: WebAssembly.instantiateStreaming is not a function"},{"fix":"Use ESM `import { ripgrep } from 'ripgrep';` in your module. If you must use CommonJS, convert your file to an ES Module (e.g., by adding `\"type\": \"module\"` to `package.json` or changing file extension to `.mjs`), or use dynamic import: `const { ripgrep } = await import('ripgrep');`.","cause":"Attempting to import `ripgrep` using `require()` in a CommonJS module, but the package is an ES Module.","error":"ERR_REQUIRE_ESM: require() of ES Module [path/to/ripgrep.js] not supported."},{"fix":"When calling `ripgrep(args, options)`, set `buffer: true` in options to capture `stdout` and `stderr` as strings in the returned object `{ code, stdout, stderr }`. This will allow you to inspect `stderr` for `ripgrep`'s specific error messages. Also, check `preopens` options if dealing with files outside the current working directory.","cause":"Ripgrep itself exited with an error, typically due to invalid arguments, inaccessible paths, or internal WASI environment issues, but `stderr` buffering or piping was not enabled.","error":"`ripgrep` command exits with code `2` or similar error, but no `stderr` output."}],"ecosystem":"npm","meta_description":null}