Vinyl#

A virtual file format. When a file is read by src(), a Vinyl object is generated to represent the file - including the path, contents, and other metadata.

Vinyl objects can have transformations applied using plugins. They may also be persisted to the file system using dest().

When creating your own Vinyl objects - instead of generating with src() - use the external vinyl module, as shown in Usage below.

Usage#

const Vinyl = require('vinyl');
const file = new Vinyl({
cwd: '/',
base: '/test/',
path: '/test/file.js',
contents: new Buffer('var x = 123')
});
file.relative === 'file.js';
file.dirname === '/test';
file.dirname = '/specs';
file.path === '/specs/file.js';
file.basename === 'file.js';
file.basename = 'file.txt';
file.path === '/specs/file.txt';
file.stem === 'file';
file.stem = 'foo';
file.path === '/specs/foo.txt';
file.extname === '.txt';
file.extname = '.js';
file.path === '/specs/foo.js';

Signature#

new Vinyl([options])

Parameters#

parametertypenote
optionsobjectDetailed in Options below.

Returns#

An instance of the Vinyl class representing a single virtual file, detailed in Vinyl instance below.

Errors#

When any passed options don't conform to the instance property definitions (like if path is set to a number) throws as defined in the table.

Options#

nametypedefaultnote
cwdstringprocess.cwd()The directory from which relative paths will be derived. Will be normalized and have trailing separators removed.
basestringUsed to calculate the relative instance property. Falls back to the value of cwd if not set. Typically set to the glob base. Will be normalized and have trailing separators removed.
pathstringThe full, absolute file path. Will be normalized and have trailing separators removed.
historyarray[ ]An array of paths to pre-populate the history of a Vinyl instance. Usually comes from deriving a new Vinyl object from a previous Vinyl object. If path and history are both passed, path is appended to history. Each item will be normalized and have trailing separators removed.
statobjectAn instance of fs.Stats, usually the result of calling fs.stat() on a file. Used to determine if a Vinyl object represents a directory or symbolic link.
contentsReadableStream
Buffer
null
nullThe contents of the file. If contents is a ReadableStream, it is wrapped in a cloneable-readable stream.

Any other properties on options will be directly assigned to the Vinyl instance.

const Vinyl = require('vinyl');
const file = new Vinyl({ foo: 'bar' });
file.foo === 'bar';

Vinyl instance#

Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.

Instance properties#

All internally managed paths - any instance property except contents and stat - are normalized and have trailing separators removed. See Normalization and concatenation for more information.

propertytypedescriptionthrows
contentsReadableStream
Buffer
null
Gets and sets the contents of the virtual file. If set to a ReadableStream, it is wrapped in a cloneable-readable stream.If set to any value other than a ReadableStream, a Buffer, or null.
statobjectGets and sets an instance of fs.Stats. Used when determining if a Vinyl object represents a directory or symbolic link.
cwdstringGets and sets the current working directory. Used for deriving relative paths.If set to an empty string or any non-string value.
basestringGets and sets the base directory. Used to calculate the relative instance property. On a Vinyl object generated by src() will be set to the glob base. If set to null or undefined, falls back to the value of the cwd instance property.If set to an empty string or any non-string value (except null or undefined).
pathstringGets and sets the full, absolute file path. Setting to a value different from the current path appends the new path to the history instance property.If set to any non-string value.
historyarrayArray of all path values the Vinyl object has been assigned. The first element is the original path and the last element is the current path. This property and its elements should be treated as read-only and only altered indirectly by setting the path instance property.
relativestringGets the relative path segment between the base and the path instance properties.If set to any value. If accessed when path is not available.
dirnamestringGets and sets the directory of the path instance property.If accessed when path is not available.
stemstringGets and sets the stem (filename without extension) of the path instance property.If accessed when path is not available.
extnamestringGets and sets the extension of the path instance property.If accessed when path is not available.
basenamestringGets and sets the filename (stem + extname) of the path instance property.If accessed when path is not available.
symlinkstringGets and sets the reference path of a symbolic link.If set to any non-string value.

Instance methods#

methodreturn typereturns
isBuffer()booleanIf the contents instance property is a Buffer, returns true.
isStream()booleanIf the contents instance property is a Stream, returns true.
isNull()booleanIf the contents instance property is null, returns true.
isDirectory()booleanIf the instance represents a directory, returns true. An instance is considered a directory when isNull() returns true, the stat instance property is an object, and stat.isDirectory() returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) fs.Stats object.
isSymbolic()booleanIf the instance represents a symbolic link, returns true. An instance is considered symbolic when isNull() returns true, the stat instance property is an object, and stat.isSymbolicLink() returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) fs.Stats object.
clone([options])objectA new Vinyl object with all properties cloned. By default custom properties are deep cloned. If the deep option is false, custom attributes will be shallow cloned. If the contents option is false and the contents instance property is a Buffer, the Buffer will be reused instead of cloned.
inspect()stringReturns a formatted interpretation of the Vinyl object. Automatically called by Node's console.log.

Normalization and concatenation#

All path properties are normalized by their setters. Concatenate paths with /, instead of using path.join(), and normalization will occur properly on all platforms. Never concatenate with \ - it is a valid filename character on POSIX system.

const file = new File();
file.path = '/' + 'test' + '/' + 'foo.bar';
console.log(file.path);
// posix => /test/foo.bar
// win32 => \\test\\foo.bar