child_process

Running shell commands and spawning processes from Node.js — exec, spawn, execFile, fork, and handling output.

What it is, in plain English: The child_process module lets Node.js spawn external processes. exec() runs a shell command and buffers the output — good for short commands. spawn() runs a command with streaming output — good for long-running processes. execFile() runs an executable directly (no shell — safer and faster). fork() spawns a new Node.js process and sets up message-passing between parent and child.

Running commands from Node.js

exec — run a shell command

import { exec }   from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);

// Run a git command:
const { stdout, stderr } = await execAsync("git log --oneline -5");
console.log(stdout);  // last 5 commits

// Check Node.js version:
const { stdout: version } = await execAsync("node --version");
console.log(version.trim());  // "v20.15.0"

// Handle errors:
try {
  await execAsync("ls /nonexistent");
} catch (e) {
  console.error("Command failed:", e.message);
  console.error("Exit code:", e.code);     // e.g. 2
  console.error("Stderr:", e.stderr);
}

spawn — streaming output for long commands

import { spawn } from "child_process";

// Good for: npm install, build tools, long-running processes
const install = spawn("npm", ["install"], {
  cwd:   "./my-project",  // working directory
  stdio: "pipe",          // capture stdout/stderr (default)
});

install.stdout.on("data", (chunk) => process.stdout.write(chunk));
install.stderr.on("data", (chunk) => process.stderr.write(chunk));

install.on("close", (code) => {
  if (code === 0) console.log("Install successful!");
  else            console.error(`Install failed with code ${code}`);
});

// Kill a process:
const proc = spawn("long-running-command");
setTimeout(() => proc.kill("SIGTERM"), 10000);  // kill after 10s

Shell injection risk. Never pass user input directly to exec() — it goes through the shell. Use execFile() or spawn() with an args array instead.

Try It Yourself

// child_process — run shell commands from Node.js
// import { exec, spawn, execFile, fork } from "child_process";
// import { promisify } from "util";
// const execAsync = promisify(exec);

// The four main functions:
const FUNCTIONS = {
  exec: {
    desc: "Run a shell command, buffer all output",
    use:  "Short commands (git status, ls, npm run)",
    code: `
const { stdout, stderr } = await execAsync("git log --oneline -5");
console.log(stdout);  // last 5 commits`,
  },
  execFile: {
    desc: "Run an executable directly (no shell)",
    use:  "Safer than exec, can't use shell features (&&, |)",
    code: `
const { stdout } = await execFileAsync("node", ["--version"]);
console.log(stdout.trim());  // "v20.0.0"`,
  },
  spawn: {
    desc: "Stream output as it arrives — for long-running processes",
    use:  "Build tools, compilers, video encoding",
    code: `
const proc = spawn("npm", ["install"]);
proc.stdout.on("data", chunk => process.stdout.write(chunk));
proc.on("close", code => console.log("Exit code:", code));`,
  },
  fork: {
    desc: "Spawn a new Node.js process with IPC",
    use:  "Offload CPU work to a child Node.js process",
    code: `
// parent.js:
const child = fork("worker.js");
child.send({ task: "compute", n: 40 });
child.on("message", (result) => console.log("Result:", result));

// worker.js:
process.on("message", ({ task, n }) => {
  if (task === "compute") process.send(fibonacci(n));
});`,
  },
};

Object.entries(FUNCTIONS).forEach(([fn, info]) => {
  console.log(\`\n\${fn.toUpperCase()}\`);
  console.log(\`  What: \${info.desc}\`);
  console.log(\`  Use:  \${info.use}\`);
});

// SECURITY: NEVER pass user input directly to exec/spawn without sanitisation:
// const dangerous = exec(\`ls \${userInput}\`);  // ← shell injection!
// Safe: use execFile with args array:
// execFile("ls", [userInput]);  // args passed as array, no shell expansion

fork, execFile, and advanced patterns

// fork — spawn a child Node.js process with IPC (message-passing):
import { fork } from "child_process";

// parent.js:
const child = fork("./worker.js", [], { silent: true });

child.send({ task: "fibonacci", n: 45 });

child.on("message", (result) => {
  console.log("Result:", result.value);  // fast — computed in separate process
  child.kill();
});

child.on("error", (e) => console.error("Worker error:", e));

// worker.js (in a separate file):
// process.on("message", ({ task, n }) => {
//   if (task === "fibonacci") {
//     const value = fib(n);
//     process.send({ value });
//   }
// });

// execFile — run a specific executable safely:
import { execFile } from "child_process";
const execFileAsync = promisify(execFile);

// Run a Python script:
const { stdout } = await execFileAsync("python3", ["script.py", "--input", "data.csv"]);
console.log(stdout);

// Send stdin to a process:
const proc = spawn("cat");  // cat echoes stdin to stdout
proc.stdin.write("Hello from Node.js!
");
proc.stdin.end();
proc.stdout.on("data", (d) => console.log(d.toString()));

execa — the better child_process (npm)

// npm install execa — nicer API with Promises and streams:
import { execa } from "execa";

// Simple command:
const { stdout } = await execa("git", ["log", "--oneline", "-5"]);

// Pipe between processes:
const { stdout: sorted } = await execa("sort", { inputFile: "names.txt" });

// Stream output:
const proc = execa("npm", ["run", "build"]);
proc.stdout.pipe(process.stdout);
await proc;

Process lifecycle, IPC protocol, and security

// Detached process — runs after parent exits:
const child = spawn("long-task", ["--background"], {
  detached: true,
  stdio:    "ignore",  // don't inherit parent's stdio
});
child.unref();  // parent can exit without waiting for child

// Shared stdio (inherit) — child uses parent's terminal:
spawn("vim", ["file.txt"], { stdio: "inherit" });

// Environment variables for child:
spawn("node", ["app.js"], {
  env: {
    ...process.env,         // inherit parent's env
    NODE_ENV: "production", // override/add specific vars
    PORT:     "8080",
  }
});

// IPC protocol (fork) — messages are serialised to JSON:
// Only: strings, numbers, booleans, null, arrays, plain objects
// NOT: functions, Dates, Sets, Maps, Buffers (use Uint8Array)

// Bidirectional communication pattern:
const worker = fork("./worker.js");
const pending = new Map();
let requestId = 0;

function callWorker(method, args) {
  return new Promise((resolve, reject) => {
    const id = requestId++;
    pending.set(id, { resolve, reject });
    worker.send({ id, method, args });
  });
}

worker.on("message", ({ id, result, error }) => {
  const { resolve, reject } = pending.get(id) ?? {};
  pending.delete(id);
  error ? reject(new Error(error)) : resolve(result);
});

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.