Non-blocking process execution
Run a long-lived or streaming external command while keeping the Node.js event loop responsive.
Node.js · Function
spawn
child_process.spawn() starts a new process asynchronously and returns a ChildProcess object. Supply the executable, optional argument tokens, and optional process settings.
How it works
spawn() starts the specified command asynchronously and returns a ChildProcess. Pass the executable as command, command-line tokens as args, and optional configuration such as the working directory, environment, or standard-stream modes in options; observe the returned process through its streams and lifecycle events.
Syntax
child_process.spawn(command[, args][, options])Parameters
| Name | Type | Description |
|---|---|---|
command | string | The executable command to run. |
args | string[] | Optional command-line arguments; omitted arguments default to an empty array. |
options | Object | Optional child-process configuration, including working directory, environment, standard streams, shell, timeout, and signals. |
Returns
A ChildProcess instance representing the asynchronously spawned child process.
Key points
- Use
spawn()when the parent must continue handling work while the child process runs. - The return value is a
ChildProcess, which represents and controls the launched process. - Provide the executable separately from its argument list.
- Leaving out
argsstarts the command without additional command-line arguments. - Listen for
'spawn'when successful process creation must be observed explicitly. - Use
'close'when you need confirmation that the process and its standard streams are finished.
Example: Run a child process and handle its output
import { spawn } from 'node:child_process';
const child = spawn(process.execPath, ['-e', 'console.log("hello")']);
child.stdout.on('data', (chunk) => process.stdout.write(chunk));
child.stderr.on('data', (chunk) => process.stderr.write(chunk));
child.on('close', (code, signal) => {
console.log(`closed with code=${code}, signal=${signal}`);
});Starts a Node.js child process asynchronously, forwards its output, and reports how it ended.
When to use it
Streaming subprocess output
Forward or transform output incrementally as the child writes to standard output or error.
Controlled process environments
Configure a child with a specific working directory, environment, or standard-stream arrangement.
Interview questions
QWhat does spawn() return, and is it blocking?
spawn() launches a process asynchronously and does not block the event loop. It returns a ChildProcess, whose standard streams and lifecycle events can be handled independently.
Follow-up: When would synchronous creation be preferable? spawnSync() provides equivalent functionality but blocks the event loop until the child exits or is terminated.
QHow are the command and arguments supplied?
The first argument is the executable command, while the optional args array contains separate command-line arguments. If args is omitted, Node.js uses an empty array.
Follow-up: Why keep arguments separate? Passing tokens separately avoids requiring a shell to parse a command string and makes argument boundaries explicit.
QWhat kinds of behavior can the options object control?
The options object configures execution, including the child working directory, environment, standard-stream behavior, detached mode, shell usage, and termination settings. The returned ChildProcess exposes the configured streams and process events.
Follow-up: What should be checked when using shell: true? Treat the command and arguments as security-sensitive because unsanitized input can lead to shell injection.
Related
ChildProcessspawnSyncexecexecFilefork