rimraf

rimraf is a small, battle-tested Node.js module that recursively deletes files and directories, providing a reliable cross-platform equivalent to the UNIX rm -rf command. It ships both a programmatic API (rimraf, rimrafSync, and platform-specific strategies like native, windows, and moveRemove) and a CLI binary, and automatically selects the fastest safe implementation for the current Node.js version and operating system.

Because deleting files reliably across Windows, macOS, and Linux involves subtle edge cases (locked files, EBUSY/EPERM errors, non-atomic unlink/rmdir calls), rimraf has become a de-facto standard dependency in build tools, test harnesses, and CLI utilities that need to clean up directories without reinventing platform-specific retry and fallback logic.

What You Get

• Async and sync APIs (rimraf, rimrafSync) that resolve to a boolean success value
• Multiple removal strategies (native, windows, manual, posix, moveRemove) selectable per platform or forced explicitly
• A CLI binary supporting glob patterns, verbose output, interactive confirmation, and configurable retry/backoff
• An AbortSignal-aware API for cancelling long-running directory removals
• A filter option to selectively exclude paths from deletion while still recursing into their children

Common Use Cases

• Cleaning build output directories (dist/, build/) before a fresh compile
• Removing temporary test fixtures and scratch directories between test runs
• Deleting node_modules or cache directories as part of a reset/clean npm script
• Deleting arbitrary glob-matched paths from a CLI or CI pipeline step

Under The Hood

Architecture rimraf is organized around a shared wrap/wrapSync higher-order function (src/index.ts) that normalizes single-path and array-of-paths inputs, resolves glob patterns via the glob package, and dispatches to one of five interchangeable removal strategies (native, posix, windows, manual, moveRemove), each implemented in its own module (rimraf-native.ts, rimraf-posix.ts, rimraf-windows.ts, rimraf-manual.ts, rimraf-move-remove.ts). use-native.ts decides at call time whether the built-in fs.rm can be used, falling back to the JS-implemented Windows/POSIX strategies when a filter or signal option is supplied, since Node’s native implementation doesn’t support those.

Tech Stack The project is TypeScript-first, built with tshy to emit dual ESM/CommonJS output, targets Node 20 or >=22, and depends on only two runtime packages (glob and package-json-from-dist). Testing uses tap with recorded snapshots in tap-snapshots/, linting uses oxlint, and docs are generated via typedoc.

Code Quality The test/ directory mirrors src/ one-to-one (17 files) plus an integration/ suite, with dedicated coverage for edge cases like EPERM handling (fix-eperm.ts) and ENOENT-safe readdir (ignore-enoent.ts). Modules are small and single-purpose, options parsing/validation is centralized in opt-arg.ts rather than duplicated per-strategy, and the codebase carries no any-typed escape hatches in the reviewed entry points.

API Design The public surface is intentionally narrow: rimraf/rimrafSync cover the common case, with named exports (native, windows, manual, posix, moveRemove) available for callers who need to force a specific strategy. All removal functions return a plain boolean rather than throwing on partial removal, and the CLI mirrors the same option set (--glob, --impl, --preserve-root), keeping the library and CLI mental models consistent.