Cancellation with options.signal waits for the subprocess to exit and its standard streams to close before rejecting. Stream errors still reject immediately. If the subprocess ignores the termination signal, the promise stays pending.
This cannot be set together with the stdin or stdio options, or on the destination of subprocess.pipe(). For incremental or binary input, write to the stdin of subprocess.nodeChildProcess instead.
const result = await spawn('gh', ['auth', 'login', '--with-token'], {input: token});
Iterates over each stdout line, as soon as it is available.
The iteration waits for the subprocess to end (even when using break or return). It throws if the subprocess fails. This means you do not need to call await subprocess. The only exception is an error in one of its stdio streams: then it throws right away, since the subprocess might keep running. It can be terminated through nodeChildProcess if needed. For a piped subprocess, see the completion rules of subprocess.pipe().
Similar to the | symbol in shells. Pipe the subprocess'sstdout to a second subprocess's stdin.
This resolves with that second subprocess's result. If either subprocess is rejected, this is rejected with that subprocess's error instead. The only exception is a source terminated by SIGPIPE, which the destination stopping to read normally causes. A source which ends with SIGPIPE for an unrelated reason is treated the same way, and its error stays reachable through pipedFrom. The pipeline takes the destination's outcome, like a shell does. When a source is piped to several destinations, one of them stopping to read also ends the input of the others.
After piping is set up, a piped subprocess waits for both subprocess promises to settle, including after a stdio error. The source promise returned by spawn() still reports its own stdio errors immediately.
When the subprocess fails, its promise is rejected with this error.
Subprocesses fail either when their exit code is not 0 or when terminated by a signal. Other failure reasons include misspelling the command name or using the timeout option.
Subprocess errors have the same shape as successful results, with the following additional properties.
This error class is exported, so you can use if (error instanceof SubprocessError) { ... }.
subprocessError.exitCode
Type: number | undefined
The numeric exit code of the subprocess that was run.
This is undefined when the subprocess could not be started, or when it was terminated by a signal.
subprocessError.signalName
Type: string | undefined
The name of the signal (like SIGTERM) that terminated the subprocess, sent by either:
If a signal terminated the subprocess, this property is defined. Otherwise it is undefined. The signal is included in the error message, unless the error has a cause, for example when the subprocess was canceled while it was running.
subprocessError.isCanceled
Type: boolean
Whether the signal option was aborted when this failure was reported. This does not necessarily mean that cancellation caused the failure.
Windows support
This package fixes several cross-platform issues with node:child_process. It brings full Windows support for:
Node modules binaries (without requiring the shell option). This includes running npm ... or yarn ....
When the shell option is not set, .cmd, .bat, and other files except .exe and .com are run through cmd.exe, so their arguments are escaped. This uses the same escaping as Rust, which works whether the batch file reads its arguments (%1, "%~1") or forwards them (%*), like Node modules binaries do.
[!WARNING]
Batch files can still misuse their arguments, which no escaping can prevent:
%~1 receives the escaped argument: each " is doubled, and so are the backslashes before a " or at the end.
Using %~1 outside double quotes, or %1 inside double quotes (like if "%1" == ""), lets cmd.exe interpret the argument's special characters, which allows command injection.
Forwarding arguments with call, or enabling delayed expansion, makes cmd.exe expand % or ! in them again.
Also, arguments cannot contain line breaks, and the escaping requires the cmd.exe defaults: command extensions enabled and delayed expansion disabled.
Alternatives
nano-spawn's main goal is to be small, yet useful. Nonetheless, depending on your use case, there are other ways to run subprocesses in Node.js.
Execa
Execa is a similar package: it provides the same features, but more. It is also built on top of node:child_process, and is maintained by the same people.
We recommend using Execa in most cases, unless your environment requires using small packages (for example, in a library or in a serverless function). It is definitely the best option inside scripts, servers, or apps.