Process execution for humans
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.
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 : , , , .
Install
Documentation
Execution:
Input/output:
Advanced usage:
Examples
Execution
Simple syntax
import {execa} from 'execa' ;
const {stdout} = await execa `npm run build` ;
// Print command's output
console. log (stdout); copy
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 copy
await execa ({preferLocal: true }) `eslint` ; copy
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); copy
Interleaved output
const {all} = await execa ({all: true }) `npm run build` ;
// stdout + stderr, interleaved
console. log (all); copy
Programmatic + terminal output
const {stdout} = await execa ({stdout: [ 'pipe' , 'inherit' ]}) `npm run build` ;
// stdout is also printed to the terminal
console. log (stdout); copy
const getInputString = () => { /* ... */ };
const {stdout} = await execa ({input: getInputString ()}) `sort` ;
console. log (stdout); copy
// Similar to: npm run build < input.txt
await execa ({stdin: {file: 'input.txt' }}) `npm run build` ; copy
File output
// Similar to: npm run build > output.txt
await execa ({stdout: {file: 'output.txt' }}) `npm run build` ; copy
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 ' )); copy
Streaming
Iterate over text lines
for await ( const line of execa `npm run build` ) {
if (line. includes ( 'WARN' )) {
console. warn (line);
}
} copy
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` ; copy
Web streams
const response = await fetch ( 'https://example.com' );
await execa ({stdin: response.body}) `sort` ; copy
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' ),
); copy
IPC
Exchange messages
// parent.js
import {execaNode} from 'execa' ;
const subprocess = execaNode `child.js` ;
await subprocess. sendMessage ( 'Hello from parent' );
const message = await subprocess. getOneMessage ();
console. log (message); // 'Hello from child' copy
// child.js
import {getOneMessage, sendMessage} from 'execa' ;
const message = await getOneMessage (); // 'Hello from parent'
const newMessage = message. replace ( 'parent' , 'child' ); // 'Hello from child'
await sendMessage (newMessage); copy
// main.js
import {execaNode} from 'execa' ;
const ipcInput = [
{task: 'lint' , ignore: /test\.js/ },
{task: 'copy' , files: new Set ([ 'main.js' , 'index.js' ]),
}];
await execaNode ({ipcInput}) `build.js` ; copy
// build.js
import {getOneMessage} from 'execa' ;
const ipcInput = await getOneMessage (); copy
Any output type
// main.js
import {execaNode} from 'execa' ;
const {ipcOutput} = await execaNode `build.js` ;
console. log (ipcOutput[ 0 ]); // {kind: 'start', timestamp: date}
console. log (ipcOutput[ 1 ]); // {kind: 'stop', timestamp: date} copy
// build.js
import {sendMessage} from 'execa' ;
const runBuild = () => { /* ... */ };
await sendMessage ({kind: 'start' , timestamp: new Date ()});
await runBuild ();
await sendMessage ({kind: 'stop' , timestamp: new Date ()}); copy
Graceful termination
// main.js
import {execaNode} from 'execa' ;
const controller = new AbortController ();
setTimeout (() => {
controller. abort ();
}, 5000 );
await execaNode ({
cancelSignal: controller.signal,
gracefulCancel: true ,
}) `build.js` ; copy
// build.js
import {getCancelSignal} from 'execa' ;
const cancelSignal = await getCancelSignal ();
const url = 'https://example.com/build/info' ;
const response = await fetch (url, {signal: cancelSignal}); copy
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,
Verbose mode
await execa `npm run build` ;
await execa `npm run test` ; copy
Custom logging
import {execa as execa_} from 'execa' ;
import {createLogger, transports} from 'winston' ;
// Log to a file using Winston
const transport = new transports. File ({filename: 'logs.txt' });
const logger = createLogger ({transports: [transport]});
const LOG_LEVELS = {
command: 'info' ,
output: 'verbose' ,
ipc: 'verbose' ,
error: 'error' ,
duration: 'info' ,
};
const execa = execa_ ({
verbose (verboseLine, {message,
nano-spawn - Like Execa but smaller
gulp-execa - Gulp plugin for Execa
nvexeca - Run Execa using any Node.js version
Maintainers