execa

What is execa?

The execa npm package is a process execution tool that simplifies working with child processes in Node.js. It provides a better user experience than the default child_process module by offering a promise-based API, improved Windows support, and additional convenience options.

What are execa's main functionalities?

Executing a shell command

This feature allows you to execute a shell command and obtain the result. The example shows how to execute the 'echo' command and print 'unicorns' to the console.

const execa = require('execa');

(async () => {
  const { stdout } = await execa('echo', ['unicorns']);
  console.log(stdout);
})();

Running a command synchronously

This feature is used to execute a command synchronously, blocking the event loop until the process has finished. The example synchronously executes the 'echo' command and logs the result.

const execa = require('execa');

const { stdout } = execa.sync('echo', ['unicorns']);
console.log(stdout);

Handling errors

This feature demonstrates error handling when a command fails to execute. The example attempts to run a non-existent command and catches the error.

const execa = require('execa');

(async () => {
  try {
    const { stdout } = await execa('wrong-command');
    console.log(stdout);
  } catch (error) {
    console.error('Error occurred:', error);
  }
})();

Streaming output

This feature allows you to stream the output of a command directly to the console or another stream. The example streams the output of the 'echo' command to the process's stdout.

const execa = require('execa');

const subprocess = execa('echo', ['unicorns']);
subprocess.stdout.pipe(process.stdout);

Other packages similar to execa

shelljs

ShellJS is a portable Unix shell commands implementation for Node.js. It offers a higher-level API for executing commands but does not support returning promises natively.

cross-spawn

Cross-spawn is a cross-platform solution for spawning child processes. It aims to solve compatibility issues on Windows but does not provide a promise-based API.

README

Process execution for humans

---

^{Sindre's open source work is supported by the community}

^{Special thanks to:}

---

Execa runs commands in your script, application or library. Unlike shells, it is optimized for programmatic usage. Built on top of the child_process core module.

---

One of the maintainers @ehmicky is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify Build, Plugins and Configuration for 2.5 years. Feel free to contact him on his website or on LinkedIn!

---

Features

• Simple syntax: promises and template strings, like zx.
• Script interface.
• No escaping nor quoting needed. No risk of shell injection.
• Execute locally installed binaries without npx.
• Improved Windows support: shebangs, PATHEXT, and more.
• Detailed errors and verbose mode, for debugging.
• Pipe multiple subprocesses better than in shells: retrieve intermediate results, use multiple sources/destinations, unpipe.
• Split the output into text lines, or iterate progressively over them.
• Strip unnecessary newlines.
• Get interleaved output from stdout and stderr similar to what is printed on the terminal.
• Retrieve the output programmatically and print it on the console at the same time.
• Transform or filter the input and output with simple functions.
• Redirect the input and output from/to files, strings, Uint8Arrays, iterables or objects.
• Pass Node.js streams or web streams to subprocesses, or convert subprocesses to a stream.
• Ensure subprocesses exit even when they intercept termination signals, or when the current process ends abruptly.

Install

npm install execa

Documentation

Execution:

• ▶️ Basic execution
• 💬 Escaping/quoting
• 💻 Shell
• 📜 Scripts
• 🐢 Node.js files
• 🌐 Environment
• ❌ Errors
• 🏁 Termination

Input/output:

• 🎹 Input
• 📢 Output
• 📃 Text lines
• 🤖 Binary data
• 🧙 Transforms

Advanced usage:

• 🔀 Piping multiple subprocesses
• ⏳️ Streams
• 📞 Inter-process communication
• 🐛 Debugging
• 📎 Windows
• 🔍 Difference with Bash and zx
• 🤓 TypeScript
• 📔 API reference

Examples

Execution

Simple syntax

import {execa} from 'execa';

const {stdout} = await execa`npm run build`;
// Print command's output
console.log(stdout);

Script

import {$} from 'execa';

const {stdout: name} = await $`cat package.json`.pipe`grep name`;
console.log(name);

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;

await Promise.all([
	$`sleep 1`,
	$`sleep 2`,
	$`sleep 3`,
]);

const directoryName = 'foo bar';
await $`mkdir /tmp/${directoryName}`;

Local binaries

$ npm install -D eslint

await execa({preferLocal: true})`eslint`;

Pipe multiple subprocesses

const {stdout, pipedFrom} = await execa`npm run build`
	.pipe`sort`
	.pipe`head -n 2`;

// Output of `npm run build | sort | head -n 2`
console.log(stdout);
// Output of `npm run build | sort`
console.log(pipedFrom[0].stdout);
// Output of `npm run build`
console.log(pipedFrom[0].pipedFrom[0].stdout);

Input/output

Interleaved output

const {all} = await execa({all: true})`npm run build`;
// stdout + stderr, interleaved
console.log(all);

Programmatic + terminal output

const {stdout} = await execa({stdout: ['pipe', 'inherit']})`npm run build`;
// stdout is also printed to the terminal
console.log(stdout);

Files

// Similar to: npm run build > output.txt
await execa({stdout: {file: './output.txt'}})`npm run build`;

Simple input

const {stdout} = await execa({input: getInputString()})`sort`;
console.log(stdout);

Split into text lines

const {stdout} = await execa({lines: true})`npm run build`;
// Print first 10 lines
console.log(stdout.slice(0, 10).join('\n'));

Streaming

Iterate over text lines

for await (const line of execa`npm run build`) {
	if (line.includes('WARN')) {
		console.warn(line);
	}
}

Transform/filter output

let count = 0;

// Filter out secret lines, then prepend the line number
const transform = function * (line) {
	if (!line.includes('secret')) {
		yield `[${count++}] ${line}`;
	}
};

await execa({stdout: transform})`npm run build`;

Web streams

const response = await fetch('https://example.com');
await execa({stdin: response.body})`sort`;

Convert to Duplex stream

import {execa} from 'execa';
import {pipeline} from 'node:stream/promises';
import {createReadStream, createWriteStream} from 'node:fs';

await pipeline(
	createReadStream('./input.txt'),
	execa`node ./transform.js`.duplex(),
	createWriteStream('./output.txt'),
);

Debugging

Detailed error

import {execa, ExecaError} from 'execa';

try {
	await execa`unknown command`;
} catch (error) {
	if (error instanceof ExecaError) {
		console.log(error);
	}
	/*
	ExecaError: Command failed with ENOENT: unknown command
	spawn unknown ENOENT
			at ...
			at ... {
		shortMessage: 'Command failed with ENOENT: unknown command\nspawn unknown ENOENT',
		originalMessage: 'spawn unknown ENOENT',
		command: 'unknown command',
		escapedCommand: 'unknown command',
		cwd: '/path/to/cwd',
		durationMs: 28.217566,
		failed: true,
		timedOut: false,
		isCanceled: false,
		isTerminated: false,
		isMaxBuffer: false,
		code: 'ENOENT',
		stdout: '',
		stderr: '',
		stdio: [undefined, '', ''],
		pipedFrom: []
		[cause]: Error: spawn unknown ENOENT
				at ...
				at ... {
			errno: -2,
			code: 'ENOENT',
			syscall: 'spawn unknown',
			path: 'unknown',
			spawnargs: [ 'command' ]
		}
	}
	*/
}

Verbose mode

await execa`npm run build`;
await execa`npm run test`;

Related

• gulp-execa - Gulp plugin for Execa
• nvexeca - Run Execa using any Node.js version

Maintainers

• Sindre Sorhus
• @ehmicky