Stance on plugins that replace gulp.src?

[lukehorvat]

In Writing a plugin, it states that a plugin "takes in Vinyl file objects" as input. What about a plugin that can create the vinyl stream itself, effectively replacing gulp.src?

For example, a hypothetical plugin that generates a JS vinyl file on-the-fly from an object literal:

myPlugin({ hello: 'world', cool: false })
  .pipe(uglify())
  .pipe(gulp.dest('dist'));

Is this kind of thing considered an acceptable way of writing a gulp plugin (i.e. won't get it blacklisted), or does it simply make for a "gulpfriendly" tool? Is it only acceptable if the plugin also allows itself to be used in the middle of a pipeline like a "regular" gulp plugin?

I suppose the docs could probably be clearer on this point.

[jednano]

I could also use a clear definition about the fundamental difference between a gulp plugin vs. a gulpfriendly module. What is it that draws the line between them? I'll take a stab at it here. Please correct me if I'm wrong.

A gulp plugin

• Is a module that exports a function, to which vinyl File objects can be piped. The function must return a transform stream. Example: gulp.src('*.js').pipe(foo(/* options */)).
• May optionally support plugin/module functions, to which vinyl File objects can also be piped, as long as it also returns a transform stream. Example: gulp.src('*.js').pipe(foo.doBar(/* options */)).
• Has a name that commonly starts with gulp-; though, this is not a requirement.
• Has gulpplugin as a package.json keyword for npm searches.

A gulp-friendly module

• Does not meet the requirements of a gulp plugin.
• Has gulpfriendly as a package.json keyword for npm searches.
• Returns vinyl File objects when manipulating files or supplements gulp tasks in some other way.

[yocontra]

Something that provides a src/dest/watch is a vinyl adapter not a plugin. See https://medium.com/@contrahacks/gulp-3828e8126466 for more info. Examples of vinyl adapters are vinyl-fs, vinyl-ftp (if that ever came out)

[lukehorvat]

Thanks @contra. In that post you say that "a Vinyl adapter simply exposes a .src(globs)", but I'm referring to the creation of a vinyl stream through means other than globbing.

For example, a "fake vinyl file" stream created from an object in memory:

var gulp = require('gulp');
var rev = require('gulp-rev');
var size = require('gulp-size');
var stream = require('stream');
var File = require('vinyl');

function fakeFile(file) {
  var src = new stream.Readable({ objectMode: true });
  src._read = function() {
    this.push(new File(file));
    this.push(null);
  };
  return src;
};

gulp.task("default", function() {
  return fakeFile({ path: 'fake.json', contents: new Buffer(JSON.stringify({ a: 'b' })) })
    .pipe(rev())
    .pipe(size())
    .pipe(gulp.dest('dist'));
});

What do you call this? (other than weird :stuck_out_tongue:)

Basically, I'm currently encountering a situation where my gulpfile needs to programmatically generate a particular file. I can't gulp.src it because the file doesn't physically exist.

[ghidello]

What about the recipe Make stream from buffer (memory contents)?

In the write-versions task it is shown how to create a new stream, push content into it and then use it like a gulp.src

[yocontra]

@lukehorvat Either way - if you replace src/dest/watch you are a vinyl adapter not a plugin. Being the head or tail of a stream = vinyl adapter. Simple as that.

[robrich]

Have you coined an npm tag (like vinylplugin or similar) for these vinyl adapters?

[yocontra]

@robrich No npm tag for them yet, I think vinyladapter would probably make sense

[sindresorhus]

vinyl-adapter

[dead-claudia]

I believe Browserify is a good example of this (although it is a little more than a simple gulp.src() replacement).

[dead-claudia]

And, given the definition that gulp plugins accept vinyl file objects, those hypothetical plugins are most definitely "gulp-friendly". Maybe the term "gulp-friendly" should be a little more clear cut here, and should include these source streams.

[yocontra]

@impinball Browserify doesn't return vinyl files so it is not "gulp-friendly"

[dead-claudia]

Oh. Didn't know that. (They do a pretty good job of masking that, IMO.)