vinyl-fs

What is vinyl-fs?

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.).

What are vinyl-fs's main functionalities?

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();
});

Other packages similar to vinyl-fs

graceful-fs

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

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

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.

README

vinyl-fs

Information

Package	vinyl-fs
Description	Vinyl adapter for the file system
Node Version	>= 0.10

Usage

var map = require('map-stream');
var fs = require('vinyl-fs');

var log = function(file, cb) {
  console.log(file.path);
  cb(null, file);
};

fs.src(['./js/**/*.js', '!./js/vendor/*.js'])
  .pipe(map(log))
  .pipe(fs.dest('./output'));

API

src(globs[, opt])

• Takes a glob string or an array of glob strings as the first argument.
• Globs are executed in order, so negations should follow positive globs. For example:

fs.src(['!b*.js', '*.js'])

would not exclude any files, but this would

fs.src(['*.js', '!b*.js'])

• Possible options for the second argument:

  • cwd - Specify the working directory the folder is relative to.

    • Default is process.cwd().

  • base - Specify the folder relative to the cwd. This is used to determine the file names when saving in .dest().

    • Default is where the glob begins if any.
    • Default is process.cwd() if there is no glob.

  • buffer - true or false if you want to buffer the file.

    • Default value is true.
    • false will make file.contents a paused Stream.

  • read - true or false if you want the file to be read or not. Useful for stuff like rming files.

    • Default value is true.
    • false will disable writing the file to disk via .dest().

  • since - Date or number if you only want files that have been modified since the time specified.

  • stripBOM - true or false if you want the BOM to be stripped on UTF-8 encoded files.

    • Default value is true.

  • passthrough - true or false if you want a duplex stream which passes items through and emits globbed files.

    • Default is false.

  • sourcemaps - true or false if you want files to have sourcemaps enabled.

    • Default is false.
    • Will load inline sourcemaps and resolve sourcemap links from files
    • Uses gulp-sourcemaps under the hood

  • followSymlinks - true if you want to recursively resolve symlinks to their targets; set to false to preserve them as symlinks.

    • Default is true.
    • false will make file.symlink equal the original symlink's target path.

  • Any glob-related options are documented in glob-stream and node-glob.

• Returns a Readable stream by default, or a Duplex stream if the passthrough option is set to true.

• This stream emits matching vinyl File objects.

Note: UTF-8 BOM will be stripped from all UTF-8 files read with .src.

dest(folder[, opt])

• Takes a folder path as the first argument.

• First argument can also be a function that takes in a file and returns a folder path.

• Possible options for the second argument:

  • cwd - Specify the working directory the folder is relative to.

    • Default is process.cwd().

  • base - Specify the folder relative to the cwd. This is used to determine the file names when saving in .dest().

    • Default is the cwd resolves to the folder path.
    • Can also be a function that takes in a file and returns a folder path.

  • mode - Specify the mode the files should be created with.

    • Default is the mode of the input file (file.stat.mode) if any.
    • Default is the process mode if the input file has no mode property.

  • dirMode - Specify the mode the directory should be created with.

    • Default is the process mode.

  • overwrite - Specify if existing files with the same path should be overwritten or not.

    • Default is true, to always overwrite existing files.
    • Can also be a function that takes in a file and returns true or false.

  • sourcemaps -

    • Default is null aka do not write sourcemaps.
    • Uses gulp-sourcemaps under the hood
    • Examples:
      • Write as inline comments
      • fs.dest('./', {sourcemaps: true})
      • Write as files in the same folder
      • fs.dest('./', {
        sourcemaps: {
        path: '.'
        }
        })
      • Any other options are passed through to gulp-sourcemaps
      • fs.dest('./', {
        sourcemaps: {
        path: '.',
        addComment: false,
        includeContent: false
        }
        })

• Returns a Readable/Writable stream.

• On write the stream will save the vinyl File to disk at the folder/cwd specified.

• After writing the file to disk, it will be emitted from the stream so you can keep piping these around.

• If the file has a symlink attribute specifying a target path, then a symlink will be created.

• The file will be modified after being written to this stream:

  • cwd, base, and path will be overwritten to match the folder.
  • stat.mode will be overwritten if you used a mode parameter.
  • contents will have it's position reset to the beginning if it is a stream.

symlink(folder[, opt])

• Takes a folder path as the first argument.

• First argument can also be a function that takes in a file and returns a folder path.

• Possible options for the second argument:

  • cwd - Specify the working directory the folder is relative to.

    • Default is process.cwd().

  • base - Specify the folder relative to the cwd. This is used to determine the file names when saving in .dest().

    • Default is the cwd resolves to the folder path.
    • Can also be a function that takes in a file and returns a folder path.

  • dirMode - Specify the mode the directory should be created with.

    • Default is the process mode.

• Returns a Readable/Writable stream.

• On write the stream will create a symbolic link (i.e. symlink) on disk at the folder/cwd specified.

• After creating the symbolic link, it will be emitted from the stream so you can keep piping these around.

• The file will be modified after being written to this stream:

  • cwd, base, and path will be overwritten to match the folder.