diff --git a/docs/getting-started/1-quick-start.md b/docs/getting-started/1-quick-start.md index 6f13d1078..b724e0481 100644 --- a/docs/getting-started/1-quick-start.md +++ b/docs/getting-started/1-quick-start.md @@ -52,17 +52,21 @@ npm install --save-dev gulp ``` ### Verify your gulp versions + ```sh gulp --version ``` + +Ensure the output matches the screenshot below or you might need to restart the steps in this guide. + ![Output: CLI version 2.0.1 & Local version 4.0.0][img-gulp-version-command] ### Create a gulpfile Using your text editor, create a file named gulpfile.js in your project root with these contents: ```js -function defaultTask(done) { +function defaultTask(cb) { // place code for your default task here - done(); + cb(); } exports.default = defaultTask diff --git a/docs/getting-started/3-creating-tasks.md b/docs/getting-started/3-creating-tasks.md index e14942ecf..48ea9ed64 100644 --- a/docs/getting-started/3-creating-tasks.md +++ b/docs/getting-started/3-creating-tasks.md @@ -160,17 +160,18 @@ exports.build = series( ); ``` -When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Tasks can be wrapped with the [async-once][async-once] module if this **(not recommended)** pattern is needed. +When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition. + +If you have code like this: ```js -// This pattern is NOT recommended but some edge cases might require it. -const { series } = require('gulp'); -const once = require('async-once'); +// This is INCORRECT +const { series, parallel } = require('gulp'); -const clean = once(function(cb) { +const clean = function(cb) { // body omitted cb(); -}); +}; const css = series(clean, function(cb) { // body omitted @@ -180,9 +181,32 @@ const css = series(clean, function(cb) { const javascript = series(clean, function(cb) { // body omitted cb(); -}) +}); + +exports.build = parallel(css, javascript); +``` + +Migrate to this: + +```js +const { series, parallel } = require('gulp'); + +function clean(cb) { + // body omitted + cb(); +} + +function css(cb) { + // body omitted + cb(); +} + +function javascript(cb) { + // body omitted + cb(); +} -exports.build = series(css, javascript); +exports.build = series(clean, parallel(css, javascript)); ``` [async-completion-docs]: 4-async-completion.md diff --git a/docs/getting-started/4-async-completion.md b/docs/getting-started/4-async-completion.md index ac8165246..908fcc06b 100644 --- a/docs/getting-started/4-async-completion.md +++ b/docs/getting-started/4-async-completion.md @@ -32,7 +32,7 @@ exports.default = streamTask; ```js function promiseTask() { - return Promise.resolve('some ignored value'); + return Promise.resolve('the value is ignored'); } exports.default = promiseTask; @@ -79,12 +79,12 @@ exports.default = observableTask; ### Using an error-first callback -If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `done()` in the examples below. +If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `cb()` in the examples below. ```js -function callbackTask(done) { - // `done()` should be called by some async work - done(); +function callbackTask(cb) { + // `cb()` should be called by some async work + cb(); } exports.default = callbackTask; @@ -93,9 +93,9 @@ exports.default = callbackTask; To indicate to gulp that an error occurred in a task using an error-first callback, call it with an `Error` as the only argument. ```js -function callbackError(done) { - // `done()` should be called by some async work - done(new Error('kaboom')); +function callbackError(cb) { + // `cb()` should be called by some async work + cb(new Error('kaboom')); } exports.default = callbackError; @@ -106,8 +106,8 @@ However, you'll often pass this callback to another API instead of calling it yo ```js const fs = require('fs'); -function passingCallback(done) { - fs.access('gulpfile.js', done); +function passingCallback(cb) { + fs.access('gulpfile.js', cb); } exports.default = passingCallback; diff --git a/docs/getting-started/5-working-with-files.md b/docs/getting-started/5-working-with-files.md index 38bcd581b..52490572f 100644 --- a/docs/getting-started/5-working-with-files.md +++ b/docs/getting-started/5-working-with-files.md @@ -35,7 +35,7 @@ exports.default = function() { } ``` -`dest()` is given an output directory string which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details). +`dest()` is given an output directory string and also produces a [Node stream][node-streams-docs] which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details). Most often plugins will be placed between `src()` and `dest()` using the `.pipe()` method and will transform the files within the stream. @@ -61,9 +61,9 @@ exports.default = function() { ## Output in phases -`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file is passed down the pipeline. +`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file continues down the pipeline. -This feature can be useful to create an unminified and minified file with the same pipeline. +This feature can be useful to create unminified and minified files with the same pipeline. ```js const { src, dest } = require('gulp'); diff --git a/docs/getting-started/7-using-plugins.md b/docs/getting-started/7-using-plugins.md index e14a50631..fda305530 100644 --- a/docs/getting-started/7-using-plugins.md +++ b/docs/getting-started/7-using-plugins.md @@ -103,6 +103,7 @@ exports.default = function() { const code = uglify.minify(file.contents.toString()) file.contents = Buffer.from(code) } + cb(null, file); })) .pipe(dest('output/')); } diff --git a/docs/getting-started/8-watching-files.md b/docs/getting-started/8-watching-files.md index 550b46e3e..7c9199edc 100644 --- a/docs/getting-started/8-watching-files.md +++ b/docs/getting-started/8-watching-files.md @@ -15,17 +15,17 @@ This API provides built-in delay and queueing based on most-common-use defaults. const { watch, series } = require('gulp'); function clean(cb) { - // Body omitted + // body omitted cb(); } function javascript(cb) { - // Body omitted + // body omitted cb(); } function css(cb) { - // Body omitted + // body omitted cb(); } @@ -51,7 +51,7 @@ const { watch } = require('gulp'); // All events will be watched watch('src/*.js', { events: 'all' }, function(cb) { - // Body omitted + // body omitted cb(); }); ``` @@ -67,7 +67,7 @@ const { watch } = require('gulp'); // The task will be executed upon startup watch('src/*.js', { ignoreInitial: false }, function(cb) { - // Body omitted + // body omitted cb(); }); ``` @@ -83,7 +83,7 @@ const { watch } = require('gulp'); // The task will be run (concurrently) for every change made watch('src/*.js', { queue: false }, function(cb) { - // Body omitted + // body omitted cb(); }); ``` @@ -99,7 +99,7 @@ const { watch } = require('gulp'); // The task won't be run until 500ms have elapsed since the first change watch('src/*.js', { delay: 500 }, function(cb) { - // Body omitted + // body omitted cb(); }); ```