7.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.
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.
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.
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.
Returns the same result object as child_process.spawnSync.
options
Type: Object
cwd
Type: string
Default: process.cwd()
Current working directory of the child process.
env
Type: Object
Default: process.env
Environment key-value pairs. Extends automatically from process.env. Set extendEnv to false if you don't want this.
extendEnv
Type: boolean
Default: true
Set to false if you don't want to extend the environment variables when providing the env property.
argv0
Type: string
Explicitly set the value of argv[0] sent to the child process. This will be set to command or file if not specified.
stdio
Type: Array string
Default: pipe
Child's stdio configuration.
detached
Type: boolean
Prepare child to run independently of its parent process. Specific behavior depends on the platform.
uid
Type: number
Sets the user identity of the process.
gid
Type: number
Sets the group identity of the process.
shell
Type: boolean string
Default: false
If true, runs command inside of a shell. Uses /bin/sh on UNIX and cmd.exe on Windows. A different shell can be specified as a string. The shell should understand the -c switch on UNIX or /d /s /c on Windows.
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').
localDir
Type: string
Default: process.cwd()
Preferred path to find locally installed binaries in (use with preferLocal).
input
Type: string Buffer stream.Readable
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.
encoding
Type: string
Default: utf8
Specify the character encoding used to decode the stdout and stderr output.
timeout
Type: number
Default: 0
If timeout is greater than 0, the parent will send the signal identified by the killSignal property (the default is SIGTERM) if the child runs longer than timeout milliseconds.
maxBuffer
Type: number
Default: 10000000 (10MB)
Largest amount of data in bytes allowed on stdout or stderr.
killSignal
Type: string number
Default: SIGTERM
Signal value to be used when the spawned process will be killed.
stdin
Type: string number Stream undefined null
Default: pipe
Same options as stdio.
stdout
Type: string number Stream undefined null
Default: pipe
Same options as stdio.
stderr
Type: string number Stream undefined null
Default: pipe
Same options as stdio.
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