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, since no shell is used by default
- Execution of locally installed binaries
- Interleaved
stdout/stderr
gulp-execa adds Gulp-specific features to Execa including:
- a task shortcut syntax
- configurable verbosity
- better errors
Commands can be executed either directly or inside a files stream. In streaming mode, unlike other libraries:
- commands are run in parallel, not serially
- output can be saved either 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
examplesfiles 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.
const { task } = require('gulp-execa')
module.exports.audit = task('npm audit')
exec(command, [options])
Executes command. The return value is both a promise and a child_process instance.
The promise will be resolved with the command result. If the command failed, the promise will be rejected with a nice error. If the reject: false option was used, the promise will be resolved with that error instead.
const { exec } = require('gulp-execa')
module.exports.outdated = async () => {
await exec('npm outdated')
}
stream(function, [options])
Returns a stream that executes a command on each input file.
function must:
- take a Vinyl file as argument. The most useful property is
file.pathbut other properties are available as well. - return either:
- a
commandstring - an
optionsobject with acommandproperty undefined
- a
const { src, dest } = require('gulp')
const { stream } = require('gulp-execa')
module.exports.sort = () =>
src('*.txt')
.pipe(stream(({ path }) => `sort ${path}`))
.pipe(dest('sorted'))
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 such as:
- firing a command programmatically instead of spawning a child process
- passing several files, a directory or a globbing pattern as arguments to the command
The verbose, stdout, stderr, all and stdio options cannot be used with this method.
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 Execa options can be used. Please refer to its documentation for a list of possible options.
The following options are available as well.
echo
Type: boolean
Default: true for task() and exec(), false for stream().
Whether the command should be printed on the console.
$ gulp audit
[13:09:39] Using gulpfile ~/code/gulpfile.js
[13:09:39] Starting 'audit'...
[13:09:39] [gulp-execa] npm audit
[13:09:44] Finished 'audit' after 4.96 s
verbose
Type: boolean
Default: true for task() and exec(), false for stream().
Whether both the command and its output (stdout/stderr) should be printed on the console instead of being returned in JavaScript.
$ gulp audit
[13:09:39] Using gulpfile ~/code/gulpfile.js
[13:09:39] Starting 'audit'...
[13:09:39] [gulp-execa] npm audit
== npm audit security report ===
found 0 vulnerabilities
in 27282 scanned packages
[13:09:44] Finished 'audit' after 4.96 s
result
Type: string
Value: 'replace' or 'save'
Default: 'replace'
With stream(), whether the command result should:
replacethe file's contentssave: be pushed to thefile.execaarray property
const { src } = require('gulp')
const { stream } = require('gulp-execa')
const through = require('through2')
module.exports.default = () =>
src('*.js')
// Prints the number of lines of each file
.pipe(stream(({ path }) => `wc -l ${path}`, { result: 'save' }))
.pipe(
through.obj((file, encoding, func) => {
console.log(file.execa[0].stdout)
func(null, file)
}),
)
from
Type: string
Value: 'stdout', 'stderr' or 'all'
Default: 'stdout'
Which output stream to use with result: 'replace'.
const { src } = require('gulp')
const { stream } = require('gulp-execa')
const through = require('through2')
module.exports.default = () =>
src('*.js')
// Prints the number of lines of each file, including `stderr`
.pipe(
stream(({ path }) => `wc -l ${path}`, { result: 'replace', from: 'all' }),
)
.pipe(
through.obj((file, encoding, func) => {
console.log(file.contents.toString())
func(null, file)
}),
)
maxConcurrency
Type: integer
Default: 100
With stream(), how many commands to run in parallel at once.
See also
Support
For any question, don't hesitate to submit an issue on GitHub.
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
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 |
 Jonathan Haines |
![`Error [ERR_REQUIRE_ESM]: Must use import to load ES Module`](https://avatars.githubusercontent.com/u/8136211?v=4)
605 Dec 30, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
3 Oct 7, 2022
7 Mar 22, 2022
8 Sep 10, 2022
11.3k Jan 4, 2023
1.5k Jan 4, 2023
2.7k Dec 26, 2022
138 Jan 2, 2023
38 Dec 26, 2022
27 Jul 3, 2022
74 Dec 27, 2022
307 Dec 26, 2022
230 Dec 2, 2022
9 Nov 27, 2022
152 Dec 31, 2022
167 Dec 29, 2022
7 Dec 15, 2022