What does a .pipe() function return in gulp?

Question

In the following snippet, what will be the input to and output of .pipe(gulpIf('*.css', cssnano())) ?

gulp.task('useref', function(){
  return gulp.src('app/*.html')
    .pipe(useref())
    .pipe(gulpIf('*.js', uglify()))
    .pipe(gulpIf('*.css', cssnano()))
    .pipe(gulp.dest('dist'))
});

API docs (link) says .pipe(destination) returns a reference to the destination stream for setting up chain, if so .pipe(gulpIf('*.js', uglify())) will return a stream to a minified .js file, how can it be piped to .pipe(gulpIf('*.css', cssnano())) ?

The stream isn't a minified `.js` file, it's the stream of [Vinyl files](https://github.com/gulpjs/vinyl-fs) that are being processed -- e.g., the Gulp stream, not a file stream. — T.J. Crowder, May 19 '17 at 08:33
As far as I know, it's a [vinyl](https://github.com/gulpjs/vinyl) filesystem stream, not just a file. — Álvaro González, May 19 '17 at 08:33
@ÁlvaroGonzález Good golly, what astounding timing. Question's been here for 14 minutes, and we both comment almost the same thing just *one second* apart?! :-) — T.J. Crowder, May 19 '17 at 08:34
@ÁlvaroGonzález @T.J.Crowder good to know that, but the gulp.src() function seems to return stream of Vinyl files with `.html` extension so why is this stream being piped to filter out `*.js` files. Pardon me if I've misunderstood something. — Alok Mishra, May 19 '17 at 09:21
If that actually works, it's because either `useref()` or `gulpIf()` are doing some magic (for instance, adding new files to the stream). You can find out what package they belong to and read the corresponding docs. — Álvaro González, May 19 '17 at 10:58
@ÁlvaroGonzález yes its almost similiar to the link you provided. Its actually from here https://css-tricks.com/gulp-for-beginners/#article-header-id-10. — Alok Mishra, May 19 '17 at 11:06

score 1 · Accepted Answer · edited Jun 20 '20 at 09:12

Gulp is just a task runner with a rather simple base functionality. Its power comes from the extensive ecosystem of third-party packages, of which your own snippet is using a minimum of four. And I say four because that's what shows up in your gulpfile.js source code; gulp itself has 13 direct runtime dependencies:

"dependencies": {
    "archy": "^1.0.0",
    "chalk": "^1.0.0",
    "deprecated": "^0.0.1",
    "gulp-util": "^3.0.0",
    "interpret": "^1.0.0",
    "liftoff": "^2.1.0",
    "minimist": "^1.1.0",
    "orchestrator": "^0.3.0",
    "pretty-hrtime": "^1.0.0",
    "semver": "^4.1.0",
    "tildify": "^1.0.0",
    "v8flags": "^2.0.2",
    "vinyl-fs": "^0.3.0"
},

... and a similar number of direct development dependencies.

The streams that gulp passes around are provided by vinyl-fs and do not represent a single file but a virtual file-system.

As about your code, you definitively start only with HTML files:

gulp.src('app/*.html')

... but right after that you execute a third-party package called gulp-useref:

.pipe(useref())

As per its docs:

will parse the build blocks in the HTML, replace them and pass those files through. Assets inside the build blocks will be concatenated and passed through in a stream as well.

In other words, it parses the HTML file to identify/generate asset files and it gets them added to the stream for further processing.

"will parse the build blocks in the HTML" ~ what does it mean? What are build blocks here? — Alok Mishra, May 20 '17 at 10:46
@AlokMishra That's it. But, as I said, that's the specific feature of a given third-party package. — Álvaro González, May 22 '17 at 07:05

What does a .pipe() function return in gulp?

1 Answers1