The vinyl-fs npm package is a module that allows you to handle file operations in a virtual file format known as Vinyl. It is commonly used in the Gulp build system to read and write files, watch file changes, and manage file streams. Vinyl-fs abstracts file details and provides a consistent API to manipulate files regardless of the source (local file system, remote, etc.).
Reading Files
This feature allows you to read files from the filesystem using glob patterns. The example code demonstrates how to read all JavaScript files in the 'src' directory and log their paths.
const { src } = require('vinyl-fs');
src('src/*.js')
.on('data', function(file) {
console.log(file.path);
});Writing Files
This feature enables writing files to a specified directory. The code sample shows how to copy all JavaScript files from the 'src' directory to the 'output' directory.
const { src, dest } = require('vinyl-fs');
src('src/*.js')
.pipe(dest('output/'));Watching File Changes
This feature is useful for setting up a watch on files to perform actions when changes are detected. The example sets up a watcher on all JavaScript files in the 'src' directory and logs a message whenever a file changes.
const { watch } = require('vinyl-fs');
watch('src/**/*.js', function(cb) {
console.log('File changed.');
cb();
});graceful-fs is a drop-in replacement for the fs module with improvements for handling file system operations more gracefully. It does not provide the virtual file abstraction that vinyl-fs offers but enhances file system reliability, especially under high load.
through2 is a thin wrapper around Node.js streams.Transform (Streams2/3) to avoid explicit subclassing noise. It's similar to vinyl-fs in that it helps with stream manipulation, but it does not deal directly with file system operations or virtual file objects.
fs-extra adds file system methods that aren't included in the native fs module and adds promise support to fs methods. It is similar to vinyl-fs in providing more utilities for file operations, but it does not use the Vinyl abstraction or integrate directly with streaming pipelines.
Vinyl adapter for the file system.
Vinyl is a very simple metadata object that describes a file. When you think of a file, two attributes come to mind: path and contents. These are the main attributes on a Vinyl object. A file does not necessarily represent something on your computer’s file system. You have files on S3, FTP, Dropbox, Box, CloudThingly.io and other services. Vinyl can be used to describe files from all of these sources.
While Vinyl provides a clean way to describe a file, we now need a way to access these files. Each file source needs what I call a "Vinyl adapter". A Vinyl adapter simply exposes a src(globs) and a dest(folder) method. Each return a stream. The src stream produces Vinyl objects, and the dest stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as the symlink method vinyl-fs provides.
var map = require('map-stream');
var vfs = require('vinyl-fs');
var log = function(file, cb) {
console.log(file.path);
cb(null, file);
};
vfs.src(['./js/**/*.js', '!./js/vendor/*.js'])
.pipe(map(log))
.pipe(vfs.dest('./output'));
src(globs[, options])Takes a glob string or an array of glob strings as the first argument and an options object as the second.
Returns a stream of vinyl File objects.
Note: UTF-8 BOM will be stripped from all UTF-8 files read with .src unless disabled in the options.
Globs are executed in order, so negations should follow positive globs.
For example:
fs.src(['!b*.js', '*.js'])
would not exclude any files, but the following would:
fs.src(['*.js', '!b*.js'])
options.cwdThe working directory the folder is relative to.
Type: String
Default: process.cwd()
options.baseThe folder relative to the cwd. This is used to determine the file names when saving in .dest().
Type: String
Default: The part of the path before the glob (if any) begins. For example, path/to/**/*.js would resolve to path/to. If there is no glob (i.e. a file path with no pattern), then the dirname of the path is used. For example, path/to/some/file.js would resolve to path/to/some.
options.bufferWhether or not you want to buffer the file contents into memory. Setting to false will make file.contents a paused Stream.
Type: Boolean
Default: true
options.readWhether or not you want the file to be read at all. Useful for stuff like removing files. Setting to false will make file.contents null and will disable writing the file to disk via .dest().
Type: Boolean
Default: true
options.sinceOnly streams files that have been modified since the time specified.
Type: Date or Number
Default: undefined
options.stripBOMCauses the BOM to be stripped on UTF-8 encoded files. Set to false if you need the BOM for some reason.
Type: Boolean
Default: true
options.passthroughAllows .src to be used in the middle of a pipeline (using a duplex stream) which passes through all objects received and adds all files globbed to the stream.
Type: Boolean
Default: false
options.sourcemapsEnables sourcemap support on files passed through the stream. Will load inline sourcemaps and resolve sourcemap links from files. Uses gulp-sourcemaps under the hood.
Type: Boolean
Default: false
options.followSymlinks - true if you wantWhether or not to recursively resolve symlinks to their targets. Setting to false to preserve them as symlinks and make file.symlink equal the original symlink's target path.
Type: Boolean
Default: true
Any glob-related options are documented in glob-stream and node-glob. Any through2-related options are documented in through2.
dest(folder[, options])Takes a folder path string or a function as the first argument and an options object as the second. If given a function, it will be called with each vinyl File object and must return a folder path.
Returns a stream that accepts vinyl File objects, writes them to disk at the folder/cwd specified, and passes them downstream so you can keep piping these around.
Once the file is written to disk, an attempt is made to determine if the stat.mode, stat.mtime and stat.atime of the vinyl File object differ from the file on the filesystem.
If they differ and the running process owns the file, the corresponding filesystem metadata is updated.
If they don't differ or the process doesn't own the file, the attempt is skipped silently.
This functionality is disabled on Windows operating systems or any other OS that doesn't support process.getuid or process.geteuid in node. This is due to Windows having very unexpected results through usage of fs.fchmod and fs.futimes.
If the file has a symlink attribute specifying a target path, then a symlink will be created.
Note: The file will be modified after being written to this stream.
cwd, base, and path will be overwritten to match the folder.stat will be updated to match the file on the filesystem.contents will have it's position reset to the beginning if it is a stream.options.cwdThe working directory the folder is relative to.
Type: String
Default: process.cwd()
options.baseThe folder relative to the cwd. This is used to determine the file names when saving in .dest(). Can also be a function that takes in a file and returns a folder path.
Type: String or Function
Default: The cwd resolved to the folder path.
options.modeThe mode the files should be created with.
Type: Number
Default: The mode of the input file (file.stat.mode) if any, or the process mode if the input file has no mode property.
options.dirModeThe mode the directory should be created with.
Type: Number
Default: The process mode.
options.overwriteWhether or not existing files with the same path should be overwritten. Can also be a function that takes in a file and returns true or false.
Type: Boolean or Function
Default: true (always overwrite existing files)
options.sourcemapsEnables sourcemap support on files passed through the stream. Will write inline soucemaps if specified as true.
Specifying a string is shorthand for the path option. Uses gulp-sourcemaps under the hood.
Examples:
// Write as inline comments
vfs.dest('./', {
sourcemaps: true
});
// Write as files in the same folder
vfs.dest('./', {
sourcemaps: '.'
});
// Any other options are passed through to [gulp-sourcemaps]
vfs.dest('./', {
sourcemaps: {
path: '.',
addComment: false,
includeContent: false
}
});
Type: Boolean, String or Object
Default: undefined (do not write sourcemaps)
Any through2-related options are documented in through2.
symlink(folder[, options])Takes a folder path string or a function as the first argument and an options object as the second. If given a function, it will be called with each vinyl File object and must return a folder path.
Returns a stream that accepts vinyl File objects, create a symbolic link (i.e. symlink) at the folder/cwd specified, and passes them downstream so you can keep piping these around.
Note: The file will be modified after being written to this stream.
cwd, base, and path will be overwritten to match the folder.options.cwdThe working directory the folder is relative to.
Type: String
Default: process.cwd()
options.baseThe folder relative to the cwd. This is used to determine the file names when saving in .symlink(). Can also be a function that takes in a file and returns a folder path.
Type: String or Function
Default: The cwd resolved to the folder path.
options.dirModeThe mode the directory should be created with.
Type: Number
Default: The process mode.
Any through2-related options are documented in through2.
FAQs
Vinyl adapter for the file system.
The npm package vinyl-fs receives a total of 1,570,968 weekly downloads. As such, vinyl-fs popularity was classified as popular.
We found that vinyl-fs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.