ZetCode

Gulp Vinyl

last modified November 15, 2026

In this article we look at Vinyl, the virtual file object that travels through Gulp 5 pipelines. We create files, read and change their paths and contents, see how src and dest use them, and call vinyl-fs directly.

The virtual file

When src reads a file from the disk, it does not send the bytes down the pipe. It creates a Vinyl object, which describes the file: where it is, where it came from and what it contains. Every plugin receives and returns such objects. A Vinyl file does not need to exist on the disk, so a plugin can create files, rename them, or drop them, and nothing is written until dest receives them. The objects are produced by vinyl-fs, the package behind src, dest and symlink of Gulp.

Installing the project

We create an ES module project and install Gulp, vinyl and vinyl-fs. The project has a stylesheet and a script in src.

$ mkdir gulp-vinyl
$ cd gulp-vinyl
$ npm init -y
$ npm pkg set type=module
$ npm i -D gulp vinyl vinyl-fs
$ mkdir -p src/css src/js

Creating a Vinyl file

The Vinyl constructor takes an options object. The most important options are path (the absolute path of the file), base (the directory from which the relative path is computed), cwd (the working directory) and contents. We create a file in memory, with no real file behind it, and print its properties.

create.mjs
import Vinyl from 'vinyl';

const file = new Vinyl({
    cwd: '/project',
    base: '/project/src',
    path: '/project/src/css/style.css',
    contents: Buffer.from('body { margin: 0; }')
});

console.log('cwd      :', file.cwd);
console.log('base     :', file.base);
console.log('path     :', file.path);
console.log('relative :', file.relative);
console.log('dirname  :', file.dirname);
console.log('basename :', file.basename);
console.log('stem     :', file.stem);
console.log('extname  :', file.extname);
console.log('isBuffer :', file.isBuffer());
console.log('isNull   :', file.isNull());
console.log('contents :', file.contents.toString());
console.log(file);

The properties dirname, basename, stem and extname are computed from path. The most useful one is relative: it is the path relative to base, and dest uses it to decide where to write the file. The contents is a Buffer here; it can also be a stream or null. The isBuffer(), isStream() and isNull() methods tell which. Printing the object shows its relative path and its contents.

$ node create.mjs
cwd      : /project
base     : /project/src
path     : /project/src/css/style.css
relative : css/style.css
dirname  : /project/src/css
basename : style.css
stem     : style
extname  : .css
isBuffer : true
isNull   : false
contents : body { margin: 0; }
<File "css/style.css" <Buffer 62 6f 64 79 20 7b 20 6d 61 72 67 69 6e 3a 20 30 3b 20 7d>>

Changing a file

The path properties have setters: assigning to extname, stem, basename or dirname changes path, and relative follows. This is how plugins such as gulp-rename work. Every change of path is recorded in history; the first item is the original path. The clone() method makes a copy that can be changed independently, for example to produce a minified and an unminified version of a file, and the file can carry custom properties, such as data, from one plugin to another.

modify.mjs
import Vinyl from 'vinyl';

const file = new Vinyl({
    cwd: '/project',
    base: '/project/src',
    path: '/project/src/css/style.css',
    contents: Buffer.from('body { margin: 0; }')
});

file.extname = '.min.css';
console.log('after extname :', file.relative);

file.stem = 'main';
console.log('after stem    :', file.relative);

file.dirname = '/project/src/styles';
console.log('after dirname :', file.relative);

file.base = '/project';
console.log('after base    :', file.relative);

file.path = '/project/src/css/other.css';
console.log('history       :', file.history);

const copy = file.clone();
copy.contents = Buffer.from('a { color: red; }');
console.log('original      :', file.contents.toString());
console.log('clone         :', copy.contents.toString());

file.data = { author: 'Jan' };
console.log('custom        :', file.data);

Note that changing base changes relative, but not path, and that the clone has its own contents.

$ node modify.mjs
after extname : css/style.min.css
after stem    : css/main.css
after dirname : styles/main.css
after base    : src/styles/main.css
history       : [
  '/project/src/css/style.css',
  '/project/src/css/style.min.css',
  '/project/src/css/main.css',
  '/project/src/styles/main.css',
  '/project/src/css/other.css'
]
original      : body { margin: 0; }
clone         : a { color: red; }
custom        : { author: 'Jan' }

Files in a pipeline

A small plugin that prints the files shows what src produces. It is a Transform stream in object mode, as described in Gulp writing a plugin. We print the relative path, the base and the kind of file.

gulpfile.mjs
import { src, dest } from 'gulp';
import { Transform } from 'node:stream';
import path from 'node:path';

function inspect() {

    return new Transform({
        objectMode: true,
        transform(file, encoding, callback) {

            const base = path.relative(file.cwd, file.base) || '.';

            console.log(`${file.relative}  base=${base}  directory=${file.isDirectory()}  buffer=${file.isBuffer()}`);
            callback(null, file);
        }
    });
}

export function files() {

    return src('src/**/*')
        .pipe(inspect());
}

export function nested() {

    return src('src/**/*', { base: '.' })
        .pipe(inspect());
}

export function prefixed() {

    return src('src/**/*.css')
        .pipe(new Transform({
            objectMode: true,
            transform(file, encoding, callback) {
                file.basename = 'site-' + file.basename;
                callback(null, file);
            }
        }))
        .pipe(dest('dist'));
}

export function unread() {

    return src('src/**/*', { read: false })
        .pipe(inspect());
}

The glob src/**/* matches the directories too, and they arrive as files without contents: isDirectory() is true and the contents are null. The base is the part of the glob before the first wildcard, here src, so the relative paths are css/style.css and js/app.js.

$ npx gulp files --silent
css  base=src  directory=true  buffer=false
js  base=src  directory=true  buffer=false
css/style.css  base=src  directory=false  buffer=true
js/app.js  base=src  directory=false  buffer=true

The base option

The base option of src overrides the computed base. With base: '.' the relative paths include the src directory, and dest would recreate it in the output. The option is described in Gulp src and dest.

export function nested() {

    return src('src/**/*', { base: '.' })
        .pipe(inspect());
}

The base is now the project directory, printed as a dot, and the paths begin with src/.

$ npx gulp nested --silent
src/css  base=.  directory=true  buffer=false
src/js  base=.  directory=true  buffer=false
src/css/style.css  base=.  directory=false  buffer=true
src/js/app.js  base=.  directory=false  buffer=true

Reading without contents

With the option read: false the files are not read, and the contents of every file is null. This is faster and is enough when a task needs only the paths, for example to delete or to list files; such files are not written by dest: we tried it with a stylesheet and the output directory stayed empty.

export function unread() {

    return src('src/**/*', { read: false })
        .pipe(inspect());
}

The output has no buffers any more.

$ npx gulp unread --silent
css  base=src  directory=true  buffer=false
js  base=src  directory=true  buffer=false
css/style.css  base=src  directory=false  buffer=false
js/app.js  base=src  directory=false  buffer=false

Writing with dest

The dest function writes each file to the output directory joined with file.relative. A plugin that changes the name of the file changes the name of the result, without writing anything itself. The following task adds a prefix to the file name of the stylesheet; the change of basename is the only work.

export function prefixed() {

    return src('src/**/*.css')
        .pipe(new Transform({
            objectMode: true,
            transform(file, encoding, callback) {
                file.basename = 'site-' + file.basename;
                callback(null, file);
            }
        }))
        .pipe(dest('dist'));
}

The output directory has the file with the new name, in the same subdirectory.

$ npx gulp prefixed --silent
$ find dist -type f
dist/css/site-style.css

Using vinyl-fs directly

The functions of vinyl-fs do not need Gulp. They return streams, and streams can be consumed with for await, so a script can read files as Vinyl objects. The objects also have a stat property with the information from the file system. The default export of the package has the src, dest and symlink functions, the same as the Gulp ones.

vfs.mjs
import vfs from 'vinyl-fs';

for await (const file of vfs.src('src/**/*.{css,js}')) {
    console.log(file.relative, file.stat.size, 'bytes', file.contents.toString().trim());
}

The script prints the relative path, the size from stat and the contents.

$ node vfs.mjs
css/style.css 20 bytes body { margin: 0; }
js/app.js 16 bytes console.log(1);

Source

Vinyl on GitHub, vinyl-fs on GitHub, Vinyl in the Gulp documentation

In this article we have looked at Vinyl: how a file is described by path, base and contents, how the path properties and clone() are used by plugins, how src and dest use the base and the relative path, and how to use vinyl-fs without Gulp. See also the Gulp writing a plugin and Gulp rename tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.