5.1 KiB
execa 
A better
child_process
Why
- Promise interface.
- Strips EOF from the output so you don't have to
stdout.trim(). - Supports shebang binaries cross-platform.
- Improved Windows support.
- Higher max buffer. 10 MB instead of 200 KB.
- Executes locally installed binaries by name.
- Cleans up spawned processes when the parent process dies.
Install
$ npm install --save execa
Usage
const execa = require('execa');
execa('echo', ['unicorns']).then(result => {
console.log(result.stdout);
//=> 'unicorns'
});
// pipe the child process stdout to the current stdout
execa('echo', ['unicorns']).stdout.pipe(process.stdout);
execa.shell('echo unicorns').then(result => {
console.log(result.stdout);
//=> 'unicorns'
});
// example of catching an error
execa.shell('exit 3').catch(error => {
console.log(error);
/*
{
message: 'Command failed: /bin/sh -c exit 3'
killed: false,
code: 3,
signal: null,
cmd: '/bin/sh -c exit 3',
stdout: '',
stderr: '',
timedOut: false
}
*/
});
API
execa(file, [arguments], [options])
Execute a file.
Same options as child_process.spawn.
Think of this as a mix of child_process.execFile and child_process.spawn.
Returns a child_process instance, which is enhanced to also be a Promise for a result Object with stdout and stderr properties.
execa.stdout(file, [arguments], [options])
Same as execa(), but returns only stdout.
execa.stderr(file, [arguments], [options])
Same as execa(), but returns only stderr.
execa.shell(command, [options])
Execute a command through the system shell. Prefer execa() whenever possible, as it's both faster and safer.
Same options as child_process.spawn.
Returns a child_process instance.
The child_process instance is enhanced to also be promise for a result object with stdout and stderr properties.
execa.sync(file, [arguments], [options])
Execute a file synchronously.
Same options as child_process.spawnSync, except the default encoding is utf8 instead of buffer.
Returns the same result object as child_process.spawnSync.
This method throws an Error if the command fails.
execa.shellSync(file, [options])
Execute a command synchronously through the system shell.
Same options as child_process.spawnSync, except the default encoding is utf8 instead of buffer.
Returns the same result object as child_process.spawnSync.
options
Additional options:
stripEof
Type: boolean
Default: true
Strip EOF (last newline) from the output.
preferLocal
Type: boolean
Default: true
Prefer locally installed binaries when looking for a binary to execute.
If you $ npm install foo, you can then execa('foo').
input
Type: string Buffer ReadableStream
Write some input to the stdin of your binary.
Streams are not allowed when using the synchronous methods.
reject
Type: boolean
Default: true
Setting this to false resolves the promise with the error instead of rejecting it.
cleanup
Type: boolean
Default: true
Keep track of the spawned process and kill it when the parent process exits.
Tips
Save and pipe output from a child process
Let's say you want to show the output of a child process in real-time while also saving it to a variable.
const execa = require('execa');
const getStream = require('get-stream');
const stream = execa('echo', ['foo']).stdout;
stream.pipe(process.stdout);
getStream(stream).then(value => {
console.log('child output:', value);
});
License
MIT © Sindre Sorhus