Node.js Child Process

Spawn and manage child processes with exec, spawn, fork, and IPC communication

When to Use

• Running external programs or shell commands from Node.js
• Executing system tools (ffmpeg, imagemagick, git, curl)
• Running Node.js scripts as separate processes with IPC
• Parallelizing work across CPU cores with full process isolation

Instructions

1. exec

   for simple commands with buffered output:

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

const execAsync = promisify(exec);

const { stdout, stderr } = await execAsync('git log --oneline -5');
console.log(stdout);

2. execFile

   for running executables (no shell, safer):

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

const execFileAsync = promisify(execFile);

const { stdout } = await execFileAsync('node', ['--version']);

3. spawn

   for streaming output from long-running processes:

import { spawn } from 'node:child_process';

const child = spawn('ffmpeg', ['-i', 'input.mp4', '-c:v', 'libx264', 'output.mp4']);

child.stdout.on('data', (data) => console.log(`stdout: ${data}`));
child.stderr.on('data', (data) => console.error(`stderr: ${data}`));

child.on('close', (code) => {
  console.log(`Process exited with code ${code}`);
});

4. fork

   for Node.js worker scripts with IPC:

// parent.ts
import { fork } from 'node:child_process';

const child = fork('./worker.ts');

child.send({ task: 'process', data: [1, 2, 3] });

child.on('message', (result) => {
  console.log('Result from child:', result);
});

// worker.ts
process.on('message', (msg: any) => {
  const result = msg.data.map((n: number) => n * 2);
  process.send!(result);
});

5. Handle errors and exit codes:

import { spawn } from 'node:child_process';

function run(command: string, args: string[]): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = spawn(command, args);
    let stdout = '';
    let stderr = '';

    child.stdout.on('data', (data) => {
      stdout += data;
    });
    child.stderr.on('data', (data) => {
      stderr += data;
    });

    child.on('error', reject); // Spawn error (command not found)
    child.on('close', (code) => {
      if (code === 0) resolve(stdout);
      else reject(new Error(`Exit code ${code}: ${stderr}`));
    });
  });
}

6. Set environment and working directory:

const child = spawn('npm', ['run', 'build'], {
  cwd: '/path/to/project',
  env: { ...process.env, NODE_ENV: 'production' },
  timeout: 60_000,
});

7. Kill processes on cleanup:

const child = spawn('long-running-process');

process.on('SIGTERM', () => {
  child.kill('SIGTERM');
});

// Or with AbortController
const ac = new AbortController();
const child = spawn('command', [], { signal: ac.signal });
ac.abort(); // Kills the child process

Details

exec

spawn

fork

exec

spawn

fork

• exec

  — shell, buffered output, 1MB default limit. Best for short commands

• spawn

  — no shell (by default), streaming output, no buffer limit. Best for long-running or large-output processes

• fork

  — specialized

  spawn

  for Node.js scripts with IPC. Best for parallel Node.js work

Security:

exec

exec

execFile

spawn

Trade-offs:

• exec

  is simple — but buffers all output in memory and uses a shell

• spawn

  streams output — but requires manual output collection

• fork

  has built-in IPC — but only works with Node.js scripts
• Child processes have full isolation — but higher overhead than worker threads

Source

https://nodejs.org/api/child_process.html

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.