Gulp.js command execution for humans

Gulp.js command execution for humans.

As opposed to similar plugins or to child_process.exec() , this uses execa which provides:

• Better Windows support , including shebangs
• Faster and more secure commands, sinceno shell is used by default
• Execution of locally installed binaries
• Interleaved stdout / stderr

gulp-execa adds Gulp-specific features to execa including:

Commands can be executed either directly or inside a files stream . In, unlike other libraries:

• commands are run in parallel , not serially
• output can be savedeither in files or in variables

Example gulpfile.js :

const { src, dest } = require('gulp')
const { task, exec, stream } = require('gulp-execa')

module.exports.audit = task('npm audit')

module.exports.outdated = async () => {
  await exec('npm outdated')
}

module.exports.sort = () =>
  src('*.txt')
    .pipe(stream(({ path }) => `sort ${path}`))
    .pipe(dest('sorted'))

Demo

You can try this library:

• either directly in your browser .
• or by executing the examples files in a terminal.

Install

npm install -D gulp-execa

This plugin requires Gulp 4.

Methods

task(command, [options])

Returns a Gulp task that executes command .

Full documentation .

exec(command, [options])

Executes command . The return value is both a promise and a child_process instance .

Full documentation .

stream(function, [options])

Returns a stream that executes a command on each input file. function must take a file as argument and return a command .

Each file in the stream will spawn a separate process. This can consume lots of resources so you should only use this method when there are no alternatives.

Full documentation .

Command

By default no shell interpreter (like Bash or cmd.exe ) is used. This means command must be just the program and its arguments. No escaping/quoting is needed, except for significant spaces (with a backslash).

Shell features such as globbing, variables and operators (like && > ; ) should not be used. All of this can be done directly in Node.js instead.

Shell interpreters are slower, less secure and less cross-platform. However, you can still opt-in to using them with the shell option .

const { writeFileStream } = require('fs')

const { series } = require('gulp')

// Wrong
module.exports.check = task('npm audit && npm outdated')

// Correct
module.exports.check = series(task('npm audit'), task('npm outdated'))

// Wrong
module.exports.install = task('npm install > log.txt')

// Correct
module.exports.install = task('npm install', {
  stdout: writeFileStream('log.txt'),
})

Options

options is an optional object.

All options from both child_process.spawn() and child_process.exec() are available: cwd , env , argv0 , stdio , detached , uid , gid , shell , encoding , timeout , maxBuffer , killSignal , windowsVerbatimArguments , windowsHide .

All execa options can also be used: cleanup , preferLocal , localDir , buffer , input , stdin , stdout , stderr , reject , stripFinalNewline , extendEnv .

The following options are available as well.

echo

Type : boolean
Default : true forand, false for.

Whether the command should be printed on the console.

Full documentation .

verbose

Type : boolean
Default : true forand, false for.

Whether both the command and its output ( stdout / stderr ) should be printed on the console instead of being returned in JavaScript.

Full documentation .

result

Type : string
Value : 'replace' or 'save'
Default : 'replace'

With, whether the command result should:

• replace the file's contents
• save : be pushed to the file.execa array property

Full documentation .

from

Type : string
Value : 'stdout' , 'stderr' or 'all'
Default : 'stdout'

Which output stream to use with.

Full documentation .

maxConcurrency

Type : integer
Default : 100

With, how many commands to run in parallel at once.

See also

• execa

Support

If you found a bug or would like a new feature, don't hesitate to submit an issue on GitHub .

For other questions, feel free to chat with us on Gitter .

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with :heart: . The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines . Pull requests are welcome!

Thanks go to our wonderful contributors:

ehmicky
:computer: :book: Jonathan Haines
:bug: