Node.js Child Processes

Node.js Child Processes: Running External Tools Safely

The node:child_process module lets Node.js launch external system binaries—such as git, ffmpeg, python, or mysqldump—in separate OS processes and stream their output. Choosing execFile() or spawn() instead of exec() prevents shell injection vulnerabilities and handles large outputs efficiently.

Choosing Between execFile(), spawn(), and exec()

Pick the child-process API based on security, output size, and whether you need a shell.

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const execFileAsync = promisify(execFile);

async function getNodeVersionSafely() {
  const { stdout } = await execFileAsync('node', ['--version'], {
    timeout: 5000,
  });
  console.log('Child reported Node:', stdout.trim());
}

getNodeVersionSafely().catch(console.error);

Preventing Command Injection

Never pass user input into exec(\convert ${userFile}`)or set{ shell: true }. An attacker passing photo.jpg; rm -rf /can execute arbitrary shell commands. Always useexecFile()orspawn() and pass arguments as a separate string array (['--format', 'png', safePath]`) so arguments are never interpreted by a shell.

Common Mistakes to Avoid

• Using exec() on large outputs: exec() buffers output in memory and crashes once output exceeds maxBuffer (default 1 MB). Use spawn() and stream child.stdout instead.
• Skipping timeout and error listeners: External tools can hang forever or fail to spawn (ENOENT). Always pass a timeout and listen to child.on('error', ...).
• Using spawnSync() inside an HTTP server: Synchronous child processes freeze the entire Node.js event loop until the child finishes.

Frequently Asked Questions

When should I use child_process vs worker_threads?

Use child_process when running non-JavaScript binaries (ffmpeg, git, python). Use worker_threads for CPU-heavy JavaScript work inside the same Node process.

How do I pass data back and forth with a Node child process?

Use fork('./worker-script.js'), which opens an IPC channel letting parent and child exchange JSON objects via child.send() and process.on('message').

Why does spawn('npm', ...) fail with ENOENT on Windows?

On Windows, npm is a .cmd batch wrapper (npm.cmd). Resolve the proper executable or handle Windows binary names cleanly without passing untrusted arguments to a shell.