cross-spawn

cross-spawn solves a long list of platform-specific bugs in Node’s built-in child_process.spawn and spawnSync on Windows: ignored PATHEXT, no shebang support, broken handling of commands containing spaces, failures on posix-style relative paths, and mis-escaped arguments when calling .cmd shims in node_modules/.bin/. It exposes the exact same API as Node’s native spawn functions, so it works as a one-line import swap in existing code.

Internally it resolves the target executable with which, reads the first bytes of the file to detect a shebang line, and — only when a shell is actually required on Windows — rewrites the command and arguments through cmd.exe with careful meta-character escaping. On POSIX platforms it defers straight to Node’s native spawn with no extra overhead.

Because so many CLI tools and build pipelines spawn child processes internally, cross-spawn has become one of the most widely depended-upon packages in the npm ecosystem, quietly making tools that were only ever tested on Linux/macOS actually work when a Windows contributor runs npm test.

What You Get

• Drop-in spawn and spawn.sync functions with the exact same signature as Node’s child_process module
• Automatic PATHEXT resolution on Windows so commands without an explicit .exe/.cmd/.bat extension are found correctly
• Shebang line detection and interpretation for scripts that Windows itself has no native concept of
• Correct handling of commands and paths containing spaces or posix-style relative segments
• Safe meta-character escaping when a command must be routed through cmd.exe, including double-escaping for node_modules/.bin shims
• An ENOENT error emitted consistently across platforms when the target command doesn’t exist, instead of a silent non-zero exit code on Windows

Common Use Cases

• Powering the child-process invocations inside cross-platform CLI tools and task runners (npm scripts, monorepo tooling, test runners)
• Spawning linters, compilers, or other locally-installed node_modules/.bin binaries from build scripts without Windows-only failures
• Running shell commands from Electron or desktop-app main processes that must behave the same on every OS
• Any library or framework that shells out to git, npm, or other external executables and needs test coverage across platforms

Under The Hood

Architecture

The library has a tiny, layered architecture: index.js is the single public entry point exposing spawn and spawn.sync, both of which funnel every call through lib/parse.js before delegating to Node’s native child_process.spawn/spawnSync. parse.js is the core transformation layer — it normalizes arguments into a parsed object, then on Windows only, detects shebangs by resolving the executable through lib/util/resolveCommand.js (backed by which) and sniffing a #! line via lib/util/readShebang.js, and — only if a shell is actually required — rewrites the command and arguments by escaping meta-characters (lib/util/escape.js) and wrapping everything in a cmd.exe /d /s /c invocation. lib/enoent.js is a separate cross-cutting concern that hooks the spawned child’s emit method to translate a Windows-specific exit-code-1 into a proper ENOENT error, keeping error semantics consistent with POSIX. Every code path ultimately returns to Node’s own spawn implementation, so cross-spawn is architecturally an adapter/transformation layer rather than a reimplementation of process spawning.

Tech Stack

cross-spawn is pure CommonJS JavaScript with no build step and only three runtime dependencies: path-key (resolves the platform-correct PATH variable name), shebang-command (parses an extracted shebang line into a runnable command), and which (PATH-based executable resolution respecting PATHEXT). Development tooling is a coherent, if dated, stack: Jest for tests with coverage, ESLint with eslint-config-moxy, Husky and lint-staged for pre-commit enforcement, commitlint for conventional commits, and standard-version for changelog-driven releases, with CI split across GitHub Actions and AppVeyor so Windows-specific behavior gets dedicated verification.

Code Quality

The test suite is thorough for the library’s scope, covering shebang detection, PATHEXT resolution, argument-escaping edge cases, and ENOENT behavior, backed by a fixtures directory of real executables and shebang scripts rather than pure mocks. Error handling is explicit and deliberate: empty catch blocks appear only where a failed which or chdir attempt is expected and has an established fallback path, not silently swallowed. There is no TypeScript or type annotations anywhere in the codebase; maintainability instead relies on ESLint and a small set of well-named, single-purpose modules.

API Design The defining design decision is that cross-spawn’s public API is intentionally identical to Node’s own child_process.spawn/spawnSync — no new concepts, no new options, just a require swap with zero learning curve. Its value isn’t a novel abstraction but a narrowly-scoped, well-documented Windows compatibility shim for a problem that every cross-platform Node CLI eventually hits.